: Re: Where do I start with C++ documentation? I am new to programming and am entirely self-taught. I have reached a point in my writing where a solid grasp of documentation standards would be greatly

@Speyer920

Vote Up Vote Down

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 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.1
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.


1 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.

(0)

Login to post a comment!