On Mon, Jul 11, 2016 at 11:01:45AM -0700, Sterling Hughes wrote: > As Will points out, I’m OK if APIs are documented outside of the code > itself. For the OS, I went through and added a bunch of Doxygen > comments, but the function calls and their variants were fairly > simple. Function calls that take big enums as a parameter can be very > lengthy to document with doxygen, and I hate having them in the code > itself.
I'm not sure how to read this. Are you saying API specifications comments are a liability? > To me, the bigger things that make it easier to learn new APIs are: > > - Consistent operation: i.e. don’t have callbacks and event queues, > don’t call functions from multiple different contexts. > - Fewer Function Calls: Easier to learn and remember a few functions, > than 100’s of them. Easier to have sample code cover all our APIs. > - Sample Code: I mostly learn through sample code — i.e. I want to do > something, how do I do it. I have no problem reading relatively complex > source code once I’ve got the basics up & running. But there should > be plenty of sample code to have that easily running. Agreed with all the above. Chris
