NaturalDocs syntax is pretty good, and the produced output is customizable enough too. However, it doesn't have full support for C++ yet, so you have to be a bit verbose in your documentation. See this page for an explanation of basic vs. full support.

Doxygen's documentation syntax is atrocious, reading it in the code is a pain, and the generated output isn't very sexy (even though it can be customized to an extent, I think).

This was the first time for me to check Doxys, and its output (linked above) didn't work in Opera at all (no navigation). Totally lame.

On another note, what kind of documentation do you guys usually write? I was first doing a lot of MSDN style documentation: summary, parameters, remarks, and "see also". Then I started recently switching to boost style, which I found to be much more succinct, and more "tied" to the code.

We've got four basic types of comment block: file header, class header, function header, and member/variable/macro tag.

In general the headers provide a brief, one-line type description of the associated chunk of code, as well as an optional extended block with information on how it fits into the overall architecture, known caveats, and so on. There's also usually a tag specifying "ownership" of the larger code chunks, so we know who to talk to if questions arise. Function headers include info on the parameters and return value, if applicable.

I don't know how we pulled it off since I've never gotten further with the Doxygen tools than running them, but our format is quite a bit more clean and readable than most Doxygen stuff I've seen:



I've never had any trouble reading the comment blocks in the code, and the generated output is decent enough but I rarely use it (just looking directly at the code is more convenient most of the time). It's certainly easier on the eyes than Microsoft's horrible XML commenting atrocity, or Javadoc for that matter.

Quote:Original post by ApochPiQ
I don't know how we pulled it off since I've never gotten further with the Doxygen tools than running them, but our format is quite a bit more clean and readable than most Doxygen stuff I've seen:

*** Source Snippet Removed ***

I've never had any trouble reading the comment blocks in the code, and the generated output is decent enough but I rarely use it (just looking directly at the code is more convenient most of the time). It's certainly easier on the eyes than Microsoft's horrible XML commenting atrocity, or Javadoc for that matter.

That doesn't look too bad, agreed. But it's still ugly, especially the part with the parameters. NaturalDocs style only replaces things like "\remarks" with "Remarks:", which is much more elegant, and doesn't make it harder to parse either. And parameters don't really need that "\param" tag--NaturalDocs just uses a simple list, e.g.:

// Parameters://     param - Description//     param2- Description

Microsoft's XML documentation is a horrible mistake, and the only way they pulled it off (other than forcing it down people's throats) was the IDE support for it.

Quote:Original post by badbrain

Quote:Original post by Muhammad Haggag
This was the first time for me to check Doxys, and its output (linked above) didn't work in Opera at all (no navigation). Totally lame.

&#106avascript disabled... that's lame.<br><br>That problem took me about 6 seconds to solve when I first encountered it.<!--QUOTE--></td></tr></table></BLOCKQUOTE><!--/QUOTE--><!--ENDQUOTE--><br>Care to enlighten me? I don't have &#106avascript disabled, assuming you assumed I had it disabled. And disabling it solved nothing, assuming you assumed I hadn't disabled it when I should have.<br><br>And either way, it's retarded to assume that people have to work around a problem in your output, be it in 6 seconds or not. I've been using Computers since 1992 and I'm not able to solve the problem so far, and I've tried <i>twice</i>.

If you're doing C++/CLI there is always NDoc.