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

[James Dennett]

On Thu, Jun 14, 2012 at 10:25 PM, Chandler Carruth <chandlerc at google.com> 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.

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