Those are all compelling reasons for me. Let's go with whatever you and Dmitri think would be best for now. :)
-eric On Wed, Feb 24, 2016 at 12:41 PM Romanova, Katya < katya_roman...@playstation.sony.com> wrote: > Hello, > > > > I don’t think it will too hard to convert C++ style doxygen comments into > C style doxygen comments by writing a post-processing python script. > However, at first we need to decide if we really want to do that. If so, we > need to settle on the exact format. After that, I need to make sure that > the comments in the new format will be rendered correctly in MS Tooltips, > XCode, online documentation and PS4 internal documentation. This discussion > + investigation might take a few days. > > > > Before we start discussing the exact format, I want to make sure that we > really want to change to C-style doxygen comments. > > Here are my not-so-strong arguments against it: > > - There currently are 257 occurrences C++ style comments in 14 > other header files in /llvm/tools/clang/lib/Headers directory (I’m talking > about the files that I didn’t touch). C++ style comments were there for > AGES and nobody complained so far. If we decide to change C++ style doxygen > comments -> C-style, we also need to change all regular C++ comments to > C-style in these header files. > > - c99 (and later) supports C++ style comments, while I c89 > doesn’t. I’m not sure if we have users that still use c89 format and x86 > intrinsic headers at the same time. > > - C++ style doxygen comments are more pretty and readable compared > to C-style comment (though it might be my subjective opinion). > > > > Let me know what you think. > > > > I will try to get Dmitri Gribenko’s opinion. He did a lot of work on > doxygen in LLVM. I’m curious what he thinks about Javadoc style format. > > > > Katya. > > > > > > *From:* Eric Christopher [mailto:echri...@gmail.com] > *Sent:* Tuesday, February 23, 2016 10:51 PM > *To:* reviews+d17550+public+bc8ce213fd9db...@reviews.llvm.org; Romanova, > Katya; Gao, Yunzhong; griboz...@gmail.com; craig.top...@gmail.com; > Robinson, Paul > *Cc:* Bedwell, Greg; cfe-commits@lists.llvm.org > *Subject:* Re: [PATCH] D17550: Adding doxygen comments to the LLVM > intrinsics (part 6, popcntintrin.h) > > > > Yeah, we should be doing this. Nice catch Paul and Greg. > > > > On Tue, Feb 23, 2016, 10:34 PM Greg Bedwell <greg_bedw...@sn.scee.net> > wrote: > > gbedwell added a subscriber: gbedwell. > gbedwell added a comment. > > In http://reviews.llvm.org/D17550#360177, @probinson wrote: > > > One question I have, which shouldn't block this (as we've done several > like this already): > > Is is okay to be using C++ style comments in these headers? > > (Is there a C-style comment that Doxygen recognizes?) > > > There are a few various formats that Doxygen supports. Looking at headers > from llvm-c the most common convention appears to be JavaDoc style, > although there are a few examples of other supported styles floating around > the codebase. E.g. from include/llvm-c/lto.h using JavaDoc style: > > /** > > - Diagnostic handler type. > - \p severity defines the severity. > - \p diag is the actual diagnostic. > - The diagnostic is not prefixed by any of severity keyword, e.g., 'error: > '. > - \p ctxt is used to pass the context set with the diagnostic handler. * > - \since LTO_API_VERSION=7 */ > > -Greg > > > Repository: > rL LLVM > > http://reviews.llvm.org/D17550 > > >
_______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits