×
INTELLIGENT WORK FORUMS
FOR COMPUTER PROFESSIONALS

Log In

Come Join Us!

Are you a
Computer / IT professional?
Join Tek-Tips Forums!
  • Talk With Other Members
  • Be Notified Of Responses
    To Your Posts
  • Keyword Search
  • One-Click Access To Your
    Favorite Forums
  • Automated Signatures
    On Your Posts
  • Best Of All, It's Free!
  • Students Click Here

*Tek-Tips's functionality depends on members receiving e-mail. By joining you are opting in to receive e-mail.

Posting Guidelines

Promoting, selling, recruiting, coursework and thesis posting is forbidden.

Students Click Here

C++ API documentor?

C++ API documentor?

C++ API documentor?

(OP)
Does anyone know of any software (if any) that has been built to compile APIs of c++ projects ... something comparable to JavaDocs in Java. Any info would be awesome.

RE: C++ API documentor?

http://en.wikipedia.org/wiki/Doxygen

--
If you dance barefoot on the broken glass of undefined behaviour, you've got to expect the occasional cut.

RE: C++ API documentor?

(OP)
muchas gracias! :)

RE: C++ API documentor?

Remember that the documentation generated is only as good as the comments and it normally doesn't say how the whole thing hangs together.  You also have to follow the rules of the package.  For instance, I tend to layout programs like

CODE

// routine description
void routine_name (
   type parameter  // parameter description
,  type parameter  // parameter description
)
{
}
which is absolutely great for maintenance since it is just a one liner to add a new parameter.  Diffs will show that this is the only line that has changed and there is a description of what the parameter does.

All the documentation engines I've tried (javadoc, doxygen and the C# one produced by MS) cannot handle this.  They would rather have

CODE

// routine description
// parameter description
// parameter description
void routine (...
What happens in maintenance is that parameters are added to the routine without the comment being updated.  When you're under pressure to get a fix out, looking above the routine declaration is not something you would normally do.  Gets even worse when a routine has lots of parameters.  The new parameter has to be inserted at the correct point in the description otherwise the comment will not match the parameters.  Often this is left as a TODO and the description never gets updated.  It could be part of the code review but in a complex fix, this is often skipped.

RE: C++ API documentor?

Doxygen uses the same format as Javadoc, so the function documentation should look like this:

CODE

/** short description
 *  long description
 *
 *  @param param1 [IN] - blah blah blah.
 *
 *  @param param2 [IN/OUT] - blah blah blah.
 *
 *  @return - blah blah bhal.
 *
 *  @throws exception type - blah blah blah.
 */
I don't use your form of documenting, but you might try using the doxygen single-line comment style to see if that helps.

CODE

type  name;  /**< blah blah blah. */

RE: C++ API documentor?

Dear xwb,

1. Enable the JAVADOC_AUTOBRIEF option in your doxygen config

2. Do this:

CODE

/// Brief description
///
/// Detailed description is optional and
/// goes here.
void routine_name (
   type parameter  ///< parameter description
,  type parameter  ///< parameter description
)
{
}

3. Profit.  (or whatever)

Ron

RE: C++ API documentor?

Thanks - I'll try that.

Red Flag This Post

Please let us know here why this post is inappropriate. Reasons such as off-topic, duplicates, flames, illegal, vulgar, or students posting their homework.

Red Flag Submitted

Thank you for helping keep Tek-Tips Forums free from inappropriate posts.
The Tek-Tips staff will check this out and take appropriate action.

Reply To This Thread

Posting in the Tek-Tips forums is a member-only feature.

Click Here to join Tek-Tips and talk with other members! Already a Member? Login

Close Box

Join Tek-Tips® Today!

Join your peers on the Internet's largest technical computer professional community.
It's easy to join and it's free.

Here's Why Members Love Tek-Tips Forums:

Register now while it's still free!

Already a member? Close this window and log in.

Join Us             Close