[PATCH] D17550: Adding doxygen comments to the LLVM intrinsics (part 6, popcntintrin.h)

[Eric Christopher via cfe-commits]

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_Romanova at 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:echristo at gmail.com]
> *Sent:* Tuesday, February 23, 2016 10:51 PM
> *To:* reviews+D17550+public+bc8ce213fd9db980 at reviews.llvm.org; Romanova,
> Katya; Gao, Yunzhong; gribozavr at gmail.com; craig.topper at gmail.com;
> Robinson, Paul
> *Cc:* Bedwell, Greg; cfe-commits at 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_bedwell at 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
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20160225/7c2356b3/attachment.html>