Sign in to follow this  
Teh Evil

Source Documentation - C++

Recommended Posts

Hi all, I am looking for a tool to write documentation for C++ code. Classes and what they does and how they're supposed to be used. So I thought I'd ask what you guys use and what you think of x and y. I've looked up doxygen but didn't use it yet. any suggestions?

Share this post


Link to post
Share on other sites
I use doxygen, but really you should use the one that provides the features you need and that you are comfortable using (you know, you will have to switch your coding style to fit in with the documentator's comment style). So it's really a matter of choice.

Share this post


Link to post
Share on other sites
I like doxygen. I feel it's worth putting in the effort to learn to use it properly. Stick with it for a while.

You can integrate it with Visual Studio too, both in terms of just hitting a button to generate documentation for a project and also to integrate the generated .chm file with the normal Visual Studio help files. So you can browse your documentation the same way as the platform documentation.

Share this post


Link to post
Share on other sites
If you use Natural Docs then you don't have to worry about special notation as such.


// Function: doSomething
// This does something with something
//
// Parameters:
//
// something - Use this to do something
//
void doSomething(int something);



The docs it generates are nice, CSS styled and IMHO look better than Doxygen output. But that's just me.

Share this post


Link to post
Share on other sites
Quote:
Original post by evolutional
If you use Natural Docs then you don't have to worry about special notation as such.

*** Source Snippet Removed ***

The docs it generates are nice, CSS styled and IMHO look better than Doxygen output. But that's just me.


yeah, first thing annoyed me in doxygen is that I should be restricted to their commenting style...

I'll give this a try, thanks...

Share this post


Link to post
Share on other sites
Quote:
Original post by Teh Evil
Quote:
Original post by evolutional
If you use Natural Docs then you don't have to worry about special notation as such.

*** Source Snippet Removed ***

The docs it generates are nice, CSS styled and IMHO look better than Doxygen output. But that's just me.


yeah, first thing annoyed me in doxygen is that I should be restricted to their commenting style...


I depends what you mean by 'special notation'. In Doxygen you wouldn't have to type in things like Function: or Parameter:

See here to see the hoops you have to jump through to get natural documentation.

I'm not having a downer on naturaldocs.org, just pointing out that you still have to put effort into documenting your code with it. They're both good products. I prefer to let doxygen take care of knowing whether something is a function or parameter, at the price of having other requirements on my coding style.

Share this post


Link to post
Share on other sites
Quote:
Original post by petewood

I depends what you mean by 'special notation'. In Doxygen you wouldn't have to type in things like Function: or Parameter:

See here to see the hoops you have to jump through to get natural documentation.

I'm not having a downer on naturaldocs.org, just pointing out that you still have to put effort into documenting your code with it. They're both good products. I prefer to let doxygen take care of knowing whether something is a function or parameter, at the price of having other requirements on my coding style.


For me, the jump was more natural as I actually documented my code in pretty much the same way before I tried natural docs. For me, it seems more intuitive - perfectly human readable but parsable by the NaturalDocs program. It was perfect for me.

As you say though, they're both good products and do what they say on the tin - it's down to personal preference when it comes down to it.

Share this post


Link to post
Share on other sites
Teh Evil, I had my own problems with Doxygen but actually like it now. I am still not very firm with it and it does take work finding out how to use it but it's quite a nice tool.

Try adding commands (which you can look up in the manual under 'special commands') like \brief, \param and \author. Also, when you open the Doxygen wizard, you can make some settings under Step 1 - Expert. You could try setting 'EXTRACT_ALL' under Build.

I hope this helps. Of course, you can just use any other tool that you can find out there if you like. Natural Docs does look quite good, too.

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

Sign in to follow this