Best Automatic Code Documenting Package?

Another member from the large Clan of Anonymous Coward asks: "I'd like to know people's experience with automatic code documentation packages, such as DOC++ and Kdoc.It seems as if they all have their advantages and disadvantages, without any being particularly 'the best'. If there's another package out there that supports both C and C++ while creating TexInfo and HTML output, that would be great!" Why limit this to just C++, code needs to be documented regardless of the language it's in.

Comments

Literal programming can automatically document

[QBasic_Dude]

Literate programming was invented around 1983 by the very famous Donald Knuth, author of the TeX typesetting system and the multi-volume series The Art of Computer Programming. It is based on two important ideas.

The first idea is that good program documentation shouldn't be squeezed into little `comments'. It should be structured more like a technical article for a journal, and it should have all the support that a journal article usually gets, including good typesetting. The programmer should have the opportunity to annotate each section of the code with as much explanation as is necessary and appropriate.

Literate programming is so interesting because the documented parts of the program do not have to be in the same order as the program itself. Code can be written in whatever order is best for people to understand, and re-ordered automatically when the compiler needs to run the program.

Documentation can be typeset automatically using tools to extract the literate comments from the code. For more information on this, see:

• Knuth's original paper on literate programming
• Literate programming in C
• Litearteprogramming.com
• POD is not Literate Programming

Re:Literal programming can automatically document

[bueller]

At my last employer we were like everyplace - a bunch of talented developers who had better things to do than write documentation. The best way to get documentation was to have it in the source code (we had guys who would only read source code to find stuff out).

After searching around for a bit and trying a few things the winning tool was doxygen. We had a mix of C, C++, and Sybase ESQL code. Doxygen is smart enough to make sense of undocumented code, but really comes into its own when you write javadoc or qt style comments. For C++ it creates browseable class hierachies, can output in HTML or LATEX and includes a search feature. Nothing better than plugging in a method/function/constant name, clicking search and seeing where it is used.

We had source code in a large hierarchy of directories that ran into hundreds of thousands of lines and it took care of it all in a couple of minutes. One tool I tried choked on the size of our code, plus because it didn't come with a proper C++ pre-processor got really tangled up.

I made the generation of the documentation part of our build and package process so each release automatically had up to date source code documentation.

It made our Delphi programmers with their fancy IDE jealous of our documentation.