<html><head></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><br><div><div>On Jun 15, 2012, at 1:29 AM, Chandler Carruth wrote:</div><br class="Apple-interchange-newline"><blockquote type="cite"><div style="font-family: arial, helvetica, sans-serif"><font size="2"><div class="gmail_quote">On Fri, Jun 15, 2012 at 1:21 AM, James Dennett <span dir="ltr"><<a href="mailto:james.dennett@gmail.com" target="_blank">james.dennett@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="im">On Thu, Jun 14, 2012 at 11:44 PM, Jacob Carlborg <<a href="mailto:doob@me.com">doob@me.com</a>> wrote:<br>
> On 2012-06-15 07:25, Chandler Carruth wrote:<br>
>> Figured it was good to ask this as James is busy making sure the Clang<br>
>> doxygen is actually all well formed, and reasonably linked together so<br>
>> we have proper docs for the ever growing number of Clang library users...<br>
>><br>
>> There are two ways to use doxygen directives:<br>
>><br>
>> /// \brief ...<br>
>><br>
>> and<br>
>><br>
>> /// @brief ...<br>
>><br>
>><br>
>> I'd like to pick one form and be consistent going forward (with no real<br>
>> intention or need to clean up existing comments) just so the bikeshed<br>
>> stays a consistent hue.<br>
>><br>
>> I prefer '\brief' by a small margin, mostly because I read all of the<br>
>> @foo things as either email stuff, twitter stuff, or ObjC stuff. Does<br>
>> anyone care passionately about this bikeshed being painted the other<br>
>> color? If so, I cede the field. I'm much more interested in having a<br>
>> single preferred form than which one it is. The mixture kills me. =]<br>
><br>
> How about doing some quick investigation and see which style is<br>
> currently used in most places.<br>
<br>
</div>Some quick numbers from just the tools/clang/ directory:<br>
<br>
jdennett@sepul:~/clang/llvm/tools/clang$ find . -name '*.h' -o -name<br>
'*.cpp' | xargs grep '[@]\(brief\|param\|return\|code\)' 2>/dev/null |<br>
wc -l<br>
177<br>
jdennett@sepul:~/clang/llvm/tools/clang$ find . -name '*.h' -o -name<br>
'*.cpp' | xargs grep '[\\]\(brief\|param\|return\|code\)' 2>/dev/null<br>
| wc -l<br>
8735<br>
<br>
For the Clang code, \command looks to be dozens of times more common<br>
than @command -- in fact it's rare enough that we _could_ choose to<br>
move Clang entirely to the \command syntax.<br>
<br>
However: outside of the tools/clang directory, for the llvm pieces I<br>
have in my working directory, there are _more_ uses of @command than<br>
\command: around 2500 for @, vs 600 for \ (for the four random<br>
commands I included in my grep pattern). If we move Clang towards<br>
\command, we might be diverging still further from the rest of the<br>
LLVM codebase.<br></blockquote><div><br></div><div>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.</div>
<div><br></div><div>Here are the holistic numbers from a checkout of llvm, clang, and compiler-rt including the relevant subdirs from the root:</div><div><br></div><div>'\command': 9396</div><div>'@command': 2853</div>
</div></font></div></blockquote><br></div><div>Let's go with \command.</div><div><br></div><div><span class="Apple-tab-span" style="white-space:pre"> </span>- Doug</div><br></body></html>