///
/// 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"]