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

[Romanova, Katya via cfe-commits]

Hi Dmitri,
Could you please let us know your opinion about C++ vs C-style doxygen comments. Read this thread for ‘pro’ and ‘con’ arguments about using C++ headers. Will LLVM online documentation look proper if we decide to use C-style headers? Which style do you personally prefer to see?

Note, that if there is any complaint in the future, it will take a couple of hours to write a python script to convert from C++ to C style doxygen comments.

Katya.

From: Eric Christopher [mailto:echristo at gmail.com]
Sent: Wednesday, February 24, 2016 6:40 PM
To: Romanova, Katya; reviews+D17550+public+bc8ce213fd9db980 at reviews.llvm.org; 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)

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<mailto: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<mailto:echristo at gmail.com>]
Sent: Tuesday, February 23, 2016 10:51 PM
To: reviews+D17550+public+bc8ce213fd9db980 at reviews.llvm.org<mailto:reviews%2BD17550%2Bpublic%2Bbc8ce213fd9db980 at reviews.llvm.org>; Romanova, Katya; Gao, Yunzhong; gribozavr at gmail.com<mailto:gribozavr at gmail.com>; craig.topper at gmail.com<mailto:craig.topper at gmail.com>; Robinson, Paul
Cc: Bedwell, Greg; cfe-commits at lists.llvm.org<mailto: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<mailto: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/20160229/d6b7208a/attachment-0001.html>