The Design of Software (CLOSED)

A public forum for discussing the design of software, from the user interface to the code architecture. Now closed.

The "Design of Software" discussion group has been merged with the main Joel on Software discussion group.

The archives will remain online indefinitely.

Documenting C++

In an effort to learn C++, I'm writing a C++ wrapper around a C network/event library I've written.

My question, where is the ideal place to document my routines?  I plan to use Javadoc style comments.  In C I generally document where the function is implemented, rather than in the header.  But with C++ I'm curious if its more ideal to do the documentation in the header where I define my class.

Opinions? Suggestions?

Thanks.
Jason Send private email
Tuesday, September 12, 2006
 
 
I document in the (public, if there's a base class) class itself, instead of their implementation. There's no hard and fast rule that i'm aware of, though.
Brian Mitchell Send private email
Tuesday, September 12, 2006
 
 
I use Javadoc style comments, with a view to allow doxygen to extract them (if needed).

I prefer to document functions in the source-files rather than the headers. The motivation is more pragmatic than anything else.

1. If a function interface changes or needs clarification, editing the header file comments could cause massive recompilation.

2. Sometimes - especially in products where source-code is not what will be sold - you need to look at the source-code *and* the function documentation simultaneously to get a clear idea of what the code does.

3. Programmers are lazy. Getting them to document anything is hard enough, and they're more likely to do it if the documentation is just within reach of the function being edited.

I document the classes and member variables in the header files though. I also give an OVERVIEW_*.h header file for a list of classes from which you can get a high-level overview of a set of source-files.
Arun RV
Tuesday, September 12, 2006
 
 
I don't know if you're laready using it, but you should check out Doxygen. http://www.stack.nl/~dimitri/doxygen/
Berislav Lopac Send private email
Tuesday, September 12, 2006
 
 
+1 for Doxygen. It generates documentation equivalent to Javadoc, as well as inheritance and dependency charts.
Andrey Butov Send private email
Tuesday, September 12, 2006
 
 
Oops, forgot to mention Doxygen in the original message, but yes, that is my reason for using Javadoc, and I currently use it to document my C (documenting functions in the .c files)..

Thanks for the replies.
Jason Send private email
Tuesday, September 12, 2006
 
 
If you like doxygen look at doxys. Basically a fork with nicer formatinng and a few easier to use features.
Martin Send private email
Tuesday, September 12, 2006
 
 
<quote>My question, where is the ideal place to document my routines?  </quote>

if you see youself/others making use of the routines then the header will be the public doc and should contain what ever info is neccessary to enable use.

The source files should be commented to help you maintian/enhance the code.

Cheers
Honu Send private email
Tuesday, September 12, 2006
 
 
Use a combination of doxygen and a wiki. Put all the tutorials and major how to stuff in your wiki. Use doxygen to generate lower level comments on the code. Generate the comments in your nightly build and have these published to a website so your wiki can link to both the source  and the doc. Do this for every build. Then developers can use the wiki to go everywhere and learn everything they need. More advanced students can add on search engines and other tools.
son of parnas
Tuesday, September 12, 2006
 
 
"My question, where is the ideal place to document my routines?"

Comment in both places.  The header should have comments that related to using the library and the implemention should document the internal details.
Almost H. Anonymous Send private email
Tuesday, September 12, 2006
 
 
Doxygen works for me. I used it for CartoType and got a job on the strength of someone liking my API design. See the CartoType web site (www.cartotype.com) if you're interested in the style of my documentation or API.
Graham Asher Send private email
Monday, September 25, 2006
 
 

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
 
Powered by FogBugz