Best Automatic Code Documenting Package? 6
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.
Literal programming can automatically document (Score:3)
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:
Re:In my expert opinion (Score:1)
Re:Literal programming can automatically document (Score:3)
After searching around for a bit and trying a few things the winning tool was doxygen [stack.nl]. 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 (Score:2)
The one that was competing with doxygen was Doc++ [imaginator.com]. Has anyone had any good or bad experience with it ? What about CERN's Root [root.cern.ch] 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 [elemental.com] 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.
Wouldn't they just obfuscate matters? (Score:1)
Re:Literal programming can automatically document (Score:1)
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).