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

[Douglas Gregor]

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>