# Anything similar to Javadoc in C++?

## Recommended Posts

PureW    127
I've been using C++ in my spare time, but never did any larger projects. But now I have this idea on a project that potentially could evolve into something large. But I'd need very detailed documentation, and since I recently began with java at the university I thought of the javadoc program which is fantastic. Now to the question, is there a similar program but for c++ that converts special comments into a detailed documentation of your code?

rip-off    10976
Doxygen?

##### Share on other sites
ApochPiQ    23004
My vote goes for Doxygen. VS2005 has an XML-based tool as well, but I'm not nearly as happy with it, since it tends to be painfully verbose (esp. compared to Doxygen).

##### Share on other sites
Spoonbender    1258
You're probably looking for Doxygen.

I'd like to point out that "very detailed documentation" is a lot more than a set of glorified code comments though. [smile]

##### Share on other sites
evolutional    1393
I prefer NaturalDocs

##### Share on other sites
what sucks about those documentation tools mentioned here is the visual format. There are big words here, small words there, colored blocks up and down the page, thin horizontal rules, fat horizontal rules, hyper links that link to an anchor on the same page, and worst of all is the description of a class's internals is packed into one page. It is inconvenient for me to have to scroll through a huge page to find what I'm looking for, especially if the page is clamored with unnecessary visual details. Documentation with these kinds of user interfaces is very puzzling.

DoxyS is the tool for the job.

On the other hand, you're looking for something similar to Javadoc.
Since DoxyS does not suck, it is prrroobably not what you're looking for. lol

##### Share on other sites
Guest Anonymous Poster
Quote:
 Original post by badbrainwhat sucks about those documentation tools mentioned here is the visual format. There are big words here, small words there, colored blocks up and down the page, thin horizontal rules, fat horizontal rules, hyper links that link to an anchor on the same page, and worst of all is the description of a class's internals is packed into one page. It is inconvenient for me to have to scroll through a huge page to find what I'm looking for, especially if the page is clamored with unnecessary visual details. Documentation with these kinds of user interfaces is very puzzling.

I agree, most of the DoxyGen output may look like a real mess, likewise for the DoxyGen source code itself, however for quite some time now DoxyGen supports not only HTML and LaTex (PDF) as output formats, but also XML-that way, you can simply use the generated XML in order to transform it to arbitrary output formats, i.e. using XSL stylesheets.

##### Share on other sites
PureW    127
I really like the screenshots from DoxyS.

##### Share on other sites
Glass_Knife    8636
If you really want JavaDocs for c++, try this one!!!

Click
The example is the documentation generated by running the old VC6 MFC
classes through the tool.

Very cool.

##### Share on other sites
Quote:
 Original post by evolutionalI prefer NaturalDocs

I second that, mainly because the documentation style is natural enough that the comments work quite well as readable comments too. (Almost no formatting.)
The output also looks quite good, which is also a plus for me.

##### Share on other sites
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.

##### Share on other sites
ApochPiQ    23004
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:

/** * Fill an index buffer with data from a mesh. * * Using the MeshLoader interface, this routine pulls mesh * information from disk and streams it into an index buffer * suitable for use with D3D. * * \remarks * - ENSURE that the buffer passed is locked and valid! * - This routine will not unlock or lock the buffer. * * \see S3D::VertexBufferFill() * * \param pRawbuffer Location to begin filling with data. * \param meshloader Object that provides the actual mesh data. * * \date 2006-06-20 (21:35) * \author Mike Lewis */

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.

##### Share on other sites
Quote:
 Original post by Muhammad HaggagThis 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.
javascript disabled... that's lame.

That problem took me about 6 seconds to solve when I first encountered it.

##### Share on other sites
Quote:
 Original post by ApochPiQI 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.

##### Share on other sites
Quote:
Quote:
 Original post by Muhammad HaggagThis 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.
javascript disabled... that's lame.

That problem took me about 6 seconds to solve when I first encountered it.

Care to enlighten me? I don't have javascript 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.

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 twice.

##### Share on other sites
That is a bug in Opera 9.01
It is related to the OnFocus event.

I discovered that one in under 1 minute

According to the W3C events specification, the way in which this attribute is being used is acceptable.

By the way, don't be intimidated by my reaction time. If it weren't for my browser plugins+keyboard shortcuts, I would be left sitting in front of my computer rolling boogers.

##### Share on other sites
capn_midnight    1707
If you're doing C++/CLI there is always NDoc.