James Dennett
2012-Jun-15 08:21 UTC
[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
Chandler Carruth
2012-Jun-15 08:29 UTC
[LLVMdev] [cfe-dev] Random, tiny question about doxygen comment style
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: <lists.llvm.org/pipermail/llvm-dev/attachments/20120615/954f4c88/attachment.html>
Douglas Gregor
2012-Jun-15 15:46 UTC
[LLVMdev] [cfe-dev] Random, tiny question about doxygen comment style
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': 2853Let's go with \command. - Doug -------------- next part -------------- An HTML attachment was scrubbed... URL: <lists.llvm.org/pipermail/llvm-dev/attachments/20120615/e82bb28a/attachment.html>