Fog Creek Software
Discussion Board




C++ Project Documentation Tools

Can anybody suggest some good automatic documentation tools for VC++/C++ projects?
I have been doing the documentaion manually so far and I like it that way. But I want to see how useful these tools are. Thanks in advance.

Joe
Saturday, January 04, 2003

Check out Doxygen
http://www.stack.nl/~dimitri/doxygen/

Matthew Lock
Sunday, January 05, 2003

I'll second doxygen. Powerful enough to get the job done, but doesn't necessitate any sort of syntax (As I recall, which may be wrong, Javadoc needs at least a little special comment syntax).

I think doxygen should be enough for most projects.

Mike Swieton
Sunday, January 05, 2003

Depends on what you mean by "Documentation". If you mean class summaries, signatures -- compilable stuff -- there are lots of tools. Check out Cocoon at http://www.stratasys.com/software/cocoon.

However, this type of data is really just labor-saving (which is fine) but it isn't what I would call documentation. I think documentation, to be really useful and time-saving, needs to be mostly natural language descriptions of classes, methods, etc. including information on how to use it, with examples, what are valid inputs, etc. Unfortunately, I don't see too much of this approach in the industry.

Aside from the fact that writing such documentation is hard work, why don't we write better (real) documentation?

Jeff Kotula
Monday, January 06, 2003

Note that "real" documentation is *hard* to write.  There are reasons why many projects hire people just to do technical writing.

IAE, I agree totally with Jeff Kotula.  Automatic documentation generation is good, but doesn't solve many problems; it just uses the obvious content that's already there.  Most of the time, the really useful documentation is that which documents the parts of the system that are not obvious.  Caveat emptor.

Brent P. Newhall
Monday, January 06, 2003

Yeah Doxygen is really good if you the code has in-line comments already... but really, most peopel just dislike documentation!

For me I usually write the code, then document it... hehe

Wei
Wednesday, January 08, 2003

*  Recent Topics

*  Fog Creek Home