Post History

Source: https://writers.stackexchange.com/a/36235
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

What you write depends on your audience. API reference documentation -- the output of tool- like Doxygen -- is usually for the _users_ of that API. Such externally-facing documentation focuses on the _contracts_ of the API and how its various components fit together -- how are you supposed to use this collection of classes and functions to write your application? For this type of documentation, I'll quote from an [answer](https://writing.stackexchange.com/a/10502/1993) I gave elsewhere (and I recommend you read the linked post):

> Here are some key points to writing good API reference documentation:
> 
> - Document the contract, not the implementation.<sup>1</sup>
> - Explain fuzzy verbs. What does "find" mean, versus "get"? Set users' expectations.
> - Document restrictions on arguments or return values that aren't fully conveyed by the signature (like that an integer has to be positive, or in the range 1-100, etc).
> - Cover failure and not just success. Can arguments be invalid? Can your code behave in abnormal ways even if the inputs are valid? How do you signal errors or other problems?
> - Be thorough but not verbose. Don't repeat information that's clear from the signature.
> 
> <sup>1</sup> To do this you need to determine what the contract actually _is_ -- what promises are you making to your users? This is a large software-design topic beyond the scope of this question.

You might also be writing documentation for _internal_ consumers -- your teammates, _yourself_ six months from now, and so on. This is where "why, not just what" becomes even more important -- they can (probably) already read the source code, but they can't read your mind about why you wrote _that_ code and not _some other_ code. Try to step back from your code and imagine that you're not intimately familiar with it already -- what parts aren't obvious to you? And what parts did you have to think about a lot during implementation? Write some comments about that. The closer the comments are to the code the more likely it is that they'll be maintained, so while you might _also_ think about external artifacts like design documents, _start_ with comments in the code. These comments can take a few forms (mix and match):

- A comment block at the top of the file that explains the overall organization and primary execution path(s).

- Comment blocks at the tops of functions that cover context (like preconditions), effects beyond the function (like that you're taking a global lock on the database), and anything interesting about the implementation.

- Inline comments near anything particularly tricky, unclear, or expensive.

Now, I said at the beginning that Doxygen output is _usually_ for users of an API. Here's why I said "usually": depending on how your code is structured, you can also use Doxygen to produce an _internal_ build -- not an _API_ reference, but a _our code guts_ reference. My team does this. Our public-facing API is limited to one namespace and directory structure; we have one Doxygen build that emits just that, and we have another that's generated from _all_ of our code, strictly for our own use. The separation in the code keeps internal documentation from leaking out to users while allowing us to write whatever code documentation we need for our own team. Sure, sometimes you don't need the Doxygen output because you can just look at the code, but we've found it helpful to have both.

Original score: 18