Professional #include contents

Question

I need to create an API that will allow my customer\'s developers to use a proprietary C module that will be released as a library (think .lib or .so -

Answer 1

One option is to generate the API documentation from the header using (for instance) Doxygen. Obviously you'd still ship the docs alongside the code.

This gives you two advantages:

1) You don't worry so much about whether something should be "in the documentation" or just "in comments in the header", because changing one is just as easy as changing the other. So everything goes in the documentation.

2) Users are less likely to go reading your header file in the first place, because they can be reasonably confident that everything of interest is in the documentation. But even if they're die-hard "I don't trust docs, I read the code" types, then they still see everything you want them to see.

The downside of auto-generated API docs is that they can be a nightmare to search, so IMO it's worth putting additional effort into writing really good "introductory" documentation. This may or may not be part of the generated API docs, depending what you prefer. For a small API, just a list of all the functions in "logical" rather than alphabetical or source order, described according to what they're for rather than what they do, can make it much easier to get into the API docs. By "logical", I mean list the commonly-used functions first, in the order that a client would call them, with alternatives which "do the same kind of thing" (such and send and sendTo for sockets) grouped together. Then list the less-commonly-used functions, and finally the obscure stuff for advanced users and unusual use cases.

One major difficulty of the approach, which can be a show-stopper, is that depending on your organisation you may have a docs team, and it may not be possible for them to edit the header. Best case scenario then is that they copy-edit what you've done and you make the changes and feed them back. Worst case scenario is the whole idea grinds to a halt because "only the docs team are supposed to write customer-facing documentation, and it must be in standard format, and we can't make Doxygen output that format".

As for "what else should you consider" - you've already said you'll follow best practices, so it's hard to add much :-)