On writing good API docs
Here’s a pro tip for writing great API documentation: Do not write for a novice audience, write as if you’re addressing an expert.
Some of the nasty questions an expert would need answers on could be:
- What happens on weird input? What happens if I put null, 0, the empty string, etc?
- Any particular exceptions that could bubble up?
- Can improper use cause resource leaks?
- Are there any conditions where the result is undefined?
- Is it thread safe?
- Is it re-entrant?
- What are the performance characteristics?
- Are there any non-obvious side effects?
Make it short and precise, not friendly and verbose. If something is obviously implied from the context, leave it out or make a brief note in the class header. Forcing yourself to imagine being questioned by this annoying expert is also a way to find corners where your code could use polish.
Novices will probably benefit more from a tutorial style document and once they get ambitious they will need the answers anyway – even though they might not understand the questions yet!