I’m getting mixed opinions about what kind of doc tags to use in the Compiz project. Overall there are two choices that everyone seems to be okay with. In no particular order the two most popular methods are:
/// /// This does that ///
Or
/** * This does that */
The latter is nice because it matches how javadoc works, which I think has made Java (and it’s APIs) one of the best documented languages around. The former I found nice because it’s easy to align in all text editors quickly (always type three forward slashes), but is more verbose. In source the former also seems to make it easier for me to quickly scan for doc tags, since most multi-line comments in C++ are done with /* notation.
Erkin pointed out that we can easily nest /// style of comments inside of /* comment blocks, which makes it easier to comment out portions of code that are documented, such as this:
/* ... code .. /// /// Method we don't want /// int foo(); ... code ... */
Feel free to make your arguments known here. If you see me on IRC feel free to bring it up, but please use the poll below or make a comment so we can get a real idea of what to commit to before we start merging all the doc’d code. This is a good way to avoid many git quilting sessions later.
[poll id="2"]
Its kinda a moot preference. But I suppose I’ll just input that I have never seen the “///” ever used before. Maybe I am writing in the wrong languages. Making a new standard is generally harder to get accepted.
I’d stick with Javadoc comments. Much easier to understand
The point of doc tags is generally that tools can be used to generate API docs from the source code, so shouldn’t the first question be, which tools are you going to use? In Java, that’s completely standardized, but for C/C++, there’s no single standard tool that I’m aware of. So it seems to me you should be picking the tools you want to use, rather than worrying abstractly about the style of the tags you use…
I didn’t know we had 29 developers O_o
Simon,
We’re using Doxygen. I didn’t include that information in the article because it was implied, sorry.