Random, tiny question about doxygen comment style

Figured it was good to ask this as James is busy making sure the Clang doxygen is actually all well formed, and reasonably linked together so we have proper docs for the ever growing number of Clang library users…

There are two ways to use doxygen directives:

/// \brief …

and

/// @brief

I’d like to pick one form and be consistent going forward (with no real intention or need to clean up existing comments) just so the bikeshed stays a consistent hue.

I prefer ‘\brief’ by a small margin, mostly because I read all of the @foo things as either email stuff, twitter stuff, or ObjC stuff. Does anyone care passionately about this bikeshed being painted the other color? If so, I cede the field. I’m much more interested in having a single preferred form than which one it is. The mixture kills me. =]

-Chandler

Figured it was good to ask this as James is busy making sure the Clang
doxygen is actually all well formed, and reasonably linked together so we
have proper docs for the ever growing number of Clang library users...

There are two ways to use doxygen directives:

/// \brief ...

and

/// @brief ...

I'd like to pick one form and be consistent going forward (with no real
intention or need to clean up existing comments) just so the bikeshed stays
a consistent hue.

Thanks for raising this. I support (moderately to strongly) the
intent to be more uniform in how Clang is documented. Either style is
fine by me, though Objective-C's use of @ is one small argument to opt
for \commands instead of @commands.

I prefer '\brief' by a small margin, mostly because I read all of the @foo
things as either email stuff, twitter stuff, or ObjC stuff.

Yes, that.

Does anyone care
passionately about this bikeshed being painted the other color? If so, I
cede the field. I'm much more interested in having a single preferred form
than which one it is. The mixture kills me. =]

I also prefer \command by a small margin, but would happily go with
whatever can get consensus.

-- James

How about doing some quick investigation and see which style is currently used in most places.

Figured it was good to ask this as James is busy making sure the Clang
doxygen is actually all well formed, and reasonably linked together so
we have proper docs for the ever growing number of Clang library users...

There are two ways to use doxygen directives:

/// \brief ...

and

/// @brief ...

I'd like to pick one form and be consistent going forward (with no real
intention or need to clean up existing comments) just so the bikeshed
stays a consistent hue.

I prefer '\brief' by a small margin, mostly because I read all of the
@foo things as either email stuff, twitter stuff, or ObjC stuff. Does
anyone care passionately about this bikeshed being painted the other
color? If so, I cede the field. I'm much more interested in having a
single preferred form than which one it is. The mixture kills me. =]

How about doing some quick investigation and see which style is
currently used in most places.

Some quick numbers from just the tools/clang/ directory:

jdennett@sepul:~/clang/llvm/tools/clang$ find . -name '*.h' -o -name
'*.cpp' | xargs grep '[@]\(brief\|param\|return\|code\)' 2>/dev/null |
wc -l
177
jdennett@sepul:~/clang/llvm/tools/clang$ find . -name '*.h' -o -name
'*.cpp' | xargs grep '[\\]\(brief\|param\|return\|code\)' 2>/dev/null

wc -l

8735

For the Clang code, \command looks to be dozens of times more common
than @command -- in fact it's rare enough that we _could_ choose to
move Clang entirely to the \command syntax.

However: outside of the tools/clang directory, for the llvm pieces I
have in my working directory, there are _more_ uses of @command than
\command: around 2500 for @, vs 600 for \ (for the four random
commands I included in my grep pattern). If we move Clang towards
\command, we might be diverging still further from the rest of the
LLVM codebase.

-- James

I think Clang has significantly more doxygen-style comments in general. I don’t think it’s worth considering the two projects separately, we should lump and count.

Here are the holistic numbers from a checkout of llvm, clang, and compiler-rt including the relevant subdirs from the root:

‘\command’: 9396
@command’: 2853

Let’s go with \command.

  • Doug