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.

Re:Literal programming can automatically document

[RGRistroph]

This ask slashdot comes at a good time for me because I am in the process of selecting a tool now.

The one that was competing with doxygen was Doc++. Has anyone had any good or bad experience with it ? What about CERN's Root tool ?

I'm leaning toward doxygen just because Mozilla is using it. While I care much more about other aspects of documentation besides class diagrams, check out this huge graph generated by doxygen on mozilla.

On one project I worked on we went the other way -- from documentation to code -- using a big FrameMaker document and tool that would convert all the tables into C struct definitions, and generate an interface library. While I think closely linking the code and the documentation is critical (preferably generating the documents in the build process, so they are never out of date) the code to document strategy seems much more flexible.

Re:Literal programming can automatically document

[bueller]

Doc++ was one of the tools I tried. It got confused with some of our source code. Root I haven't tried, but it looks good.

Now that you have a couple of candidates, do a local install of each of them and then run it across all of your existing source. Using all of your source is important - you don't want to find the tool you've selected doesn't understand namespaces or some other language feature you've used. Next take a small module and mark it up according to the guidelines for each tool and then run each of your candidates across the code again. By now you will have an obvious winner and at most it should have cost you a day of your time.

Looking at how each tool documents your code that isn't marked up is quite important when you have an existing code base. Commenting your code does take time and few managers will give you explicit permission to spend the next few weeks going back through the code base and marking it up.

When you marked up the code, how closely did it match your existing commenting style? The closer the match the easier it is to convince the programming team to use it.

Who is the target audience of your documented code? This will also affect your choice of tool. Also, does the documentation make it easier to explain the code to someone else? The class diagrams are pretty handy when explaining to someone where the method fred comes from.

Check what control you have over which comments will form part of the documentation. You don't want 'stupid hack to get around xxx' included while the detailed explanation of a clever algorithm remains hidden in the source (or maybe you do).

Re:In my expert opinion

[X]

NO!!! It's Emacs!! ;-)

Wouldn't they just obfuscate matters?

[Mr_Machine_Code]

I code in assembly, and comment nearly every line. It really helps me root out bugs, but I should think that a documentation program (I had never heard of them until now) would cause more trouble than it is worth, for these reasons: 1) If you view the comments without the code, what assurance have you got that the code actually does what the comment says it does? Even if the programmer keeps the documentation up to date, there is always the chance of typos in the code. 2) If the comments can appear in a different order than the actual operation of the program, might that not cause confusion as to the actual control flow of the code?