Why not to use documentation generators
The Java programming language has a specification for code documentation called "JavaDoc". Many C and C++ programmers use tools such as Doxygen to automatically generate code documentation with inheritance- and callgraphs. These tools are often praised and are said to force programmers to write useful documentation. This is a document on why such tools are overrated and overused.
-
Annoying
I think that often, documentation tools force programmers to get annoyed at the tools due to them expecting documentation for self-explaining functions. See Why not to use Java for a good example of useless documentation. Java's CheckStyle utility requires you to write such silly comments. "double getX() returns the X coordinate of a point in double precision. It also returns the X coordinate of a point". Just the fact that CheckStyle requires you to write a description and an @returns directive causes these redundant comments.
-
Bloated documentation
The tools generate large HTML pages with fancy links and graphs all over the place, hiding the bits and pieces of valuable code documentation. In order to still be visible, programmers tend to write even larger amounts of useless chatter just to have a bit of content on those pages of wasted space. Good examples of such chatter can be found in nearly every project that uses Doxygen. Code samples, usage notes and every possible (even if obvious) situation is explained in greatest detail. You might think this is a good thing, but what happens is that the valuable pieces of information you might need are hidden somewhere in a novel of code documentation.
-
Lazy
Documentation generators, if they do not get the programmers to write documentation for their code, makes those lazy. It may make them think they can get away with writing no documentation and letting an automated tool generate the docs for them. As a result, the produced documentation is entirely useless. Everything such a tool can do can more or less easily be seen in the code itself.
-
Bad presentation
Even if the idea of doclets in code is not that bad, the presentation of written documentation is often very bad. As mentioned in the point on bloated documentation, the HTML pages are huge and the documentation is barely visible. This is a problem with the presentation of information.
Overall, I do not think that documentation systems such as JavaDoc or Doxygen add to the value of code documentation. I have yet to see a library that I can call well-documented by means of JavaDoc.
