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

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

On Fri, Jun 15, 2012 at 1:21 AM, James Dennett <james.dennett at
gmail.com>wrote:
> 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.
>
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
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20120615/954f4c88/attachment.html>

On Jun 15, 2012, at 1:29 AM, Chandler Carruth wrote:
> On Fri, Jun 15, 2012 at 1:21 AM, James Dennett <james.dennett at
gmail.com> wrote:
> 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.
> 
> 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

-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20120615/e82bb28a/attachment.html>