[cfe-dev] Random, tiny question about doxygen comment style
James Dennett
james.dennett at gmail.com
Thu Jun 14 22:47:47 PDT 2012
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
More information about the cfe-dev
mailing list