Source Documentation - C++
Author
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?
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.
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.
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.
If you use Natural Docs then you don't have to worry about special notation as such.
The docs it generates are nice, CSS styled and IMHO look better than Doxygen output. But that's just me.
// 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.
Author
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...
Quote:Original post by Teh EvilQuote: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.
Author
You have a good point. Doxygen's docs says I can use this:
but doesn't seem to talk about how to enable it, I tried putting some lines like that but no luck still.
//// comment//but doesn't seem to talk about how to enable it, I tried putting some lines like that but no luck still.
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.
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.
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.
This topic is closed to new replies.
Advertisement
Popular Topics
Advertisement
