Chandler Carruth
2012-Jun-15 05:25 UTC
[LLVMdev] Random, tiny question about doxygen comment style
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. =] -Chandler -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20120614/7cf41ecb/attachment.html>
James Dennett
2012-Jun-15 05:47 UTC
[LLVMdev] [cfe-dev] Random, tiny question about doxygen comment style
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
Apparently Analagous Threads
- [LLVMdev] [cfe-dev] Random, tiny question about doxygen comment style
- [LLVMdev] [cfe-dev] Random, tiny question about doxygen comment style
- Stacked barplot: specifying individual bar hue/luminance
- [PATCH] drm/nv10/plane: add plane support for nv10-nv40
- Finding different hues for a mosaic plot compatible with grayscale printing