[LLVMdev] [cfe-dev] Random, tiny question about doxygen comment style

[James Dennett]

On Thu, Jun 14, 2012 at 11:44 PM, Jacob Carlborg <doob at me.com> wrote:
> On 2012-06-15 07:25, Chandler Carruth wrote:
>> 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 at sepul:~/clang/llvm/tools/clang$ find . -name '*.h' -o -name
'*.cpp' | xargs grep '[@]\(brief\|param\|return\|code\)' 2>/dev/null |
wc -l
177
jdennett at 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