How to make Doxygen documentation that helps in understanding the code

documentationquality

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?

Best Answer

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.