4

So a few years ago I came across a statement that most of the Doxygen generated documentation out there is quite bad. "Bad" in the sense that defies the purpose of documentation and doesn't help in understanding the code. To an extent, I think this also applies to other automatic documentation generators.

The majority of Doxygen-ated stuff I have seen was okay; you could work with it. Of course there's always the really bad apple that leaves scars in your memory.

So far, I've not come across some documentation which made me go: "Oh, wow, this is written really well, I love it."

My question(s):

  1. What should a developer do in order to avoid auto-generating bad documentation that doesn't help future developers?
  2. And are there additional things that could be done that would make the auto-generated documentation good so it actually helps future developers?
Improve this question
6
  • 6
    Good documentation gives brief, abstract, high-level explanation of the purpose of a function and its parameters, a class and its members, etc., and explains design decisions.Most Doxygen-generated documentation is bad because it was generated from source code with no documentation comments, so it add no information.
    – Michael Borgwardt
    Oct 16, 2014 at 9:05
  • 1
    @MichaelBorgwardt - Though Doxygen does not add information, it is able to present it in a usable form: call trees and caller trees for instance.
    – mouviciel
    Oct 16, 2014 at 9:47
  • good point about the call trees. For the rest: I found caring about readable, properly structured code follwing common best practices, breaking everything up in small blocks which do one thing and are properly named, etc, tends to severly reduce the need for documentation. Also especially for argument naming. Imagine things like StartEatingDogFood( numberOfKilogramsOfBeefFlavouredStuff ) versus StartEat( n ) :]
    – stijn
    Oct 16, 2014 at 13:56
  • 1
    Not all documentation requirements are purely for the practical benefit of other programmers. The only thing worse than having to generate bad documentation, is to do it manually.
    – JeffO
    Oct 16, 2014 at 16:15
  • @gnat: On the contrary. This not being meant as a rant. Because, seriously, I often read the statement that "Documentation generators" suck, but never I've read "why" they supposedly suck. I want to understand what people dislike about most Doxygen-ish documentation and how I can avoid those mistakes. –– Also I get the vibe (and could be wayyy off) that you (gnat) may be projecting your own beliefs into my question (not meant in any way offensive, I often do the same). Certainly you did read something into it, I didn't want to express.
    – datenwolf
    Oct 16, 2014 at 18:49

1 Answer 1

Reset to default
2

Generated documentation's audience is developers who are trying to use the code. Meaning the code is a reusable library or framework.

If code is named and structured properly, documentation is not as important. I have found that the most important documentation is at the class or module (namespace, package, etc) level. The least important documentation is at the function or method level.

In order to make the documentation meaningful and useful to developers, be sure to describe the purpose of classes and how they are used together. If I have an e.g. PrintJob class, I know what it is. But how does it interact with a PrintManager or PrinterProperties? What is the process of taking an object and printing it? How do these objects work together? I would expect to see a short code example showing the class interactions.

Generated documentation must also include pre- and post-conditions in plain English at the function level where appropriate. If your print() function expects a job to be in a certain state, tell me. I do not want to dig around in the code to decipher what it needs. Once the printing is done, can I reuse the job to print a second copy or is it now invalid?

Finally, omit documentation for entities that truly are simple and do not need it. If you have a List, you do not need to document the size() function. I understand it will be a nonnegative integer, and based on the data type, I know how big it can be. This reduces fluff. When I am scanning documentation, I know that if I see text, it is important. It is not documenting something that is common-sense to a developer.

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.