<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Generator" content="Microsoft Word 14 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
@font-face
{font-family:Tahoma;
panose-1:2 11 6 4 3 5 4 4 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
margin-bottom:.0001pt;
font-size:12.0pt;
font-family:"Times New Roman","serif";}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
{mso-style-priority:99;
color:purple;
text-decoration:underline;}
p
{mso-style-priority:99;
mso-margin-top-alt:auto;
margin-right:0in;
mso-margin-bottom-alt:auto;
margin-left:0in;
font-size:12.0pt;
font-family:"Times New Roman","serif";}
p.MsoAcetate, li.MsoAcetate, div.MsoAcetate
{mso-style-priority:99;
mso-style-link:"Balloon Text Char";
margin:0in;
margin-bottom:.0001pt;
font-size:8.0pt;
font-family:"Tahoma","sans-serif";}
span.BalloonTextChar
{mso-style-name:"Balloon Text Char";
mso-style-priority:99;
mso-style-link:"Balloon Text";
font-family:"Tahoma","sans-serif";}
span.EmailStyle20
{mso-style-type:personal-reply;
font-family:"Calibri","sans-serif";
color:#1F497D;}
.MsoChpDefault
{mso-style-type:export-only;
font-family:"Calibri","sans-serif";}
@page WordSection1
{size:8.5in 11.0in;
margin:1.0in 1.0in 1.0in 1.0in;}
div.WordSection1
{page:WordSection1;}
--></style><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]-->
</head>
<body lang="EN-US" link="blue" vlink="purple">
<div class="WordSection1">
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Hi Dmitri,<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">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?<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">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.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Katya.<o:p></o:p></span></p>
<p class="MsoNormal"><a name="_MailEndCompose"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></a></p>
<div style="border:none;border-left:solid blue 1.5pt;padding:0in 0in 0in 4.0pt">
<div>
<div style="border:none;border-top:solid #B5C4DF 1.0pt;padding:3.0pt 0in 0in 0in">
<p class="MsoNormal"><b><span style="font-size:10.0pt;font-family:"Tahoma","sans-serif"">From:</span></b><span style="font-size:10.0pt;font-family:"Tahoma","sans-serif""> Eric Christopher [mailto:echristo@gmail.com]
<br>
<b>Sent:</b> Wednesday, February 24, 2016 6:40 PM<br>
<b>To:</b> Romanova, Katya; reviews+D17550+public+bc8ce213fd9db980@reviews.llvm.org; Gao, Yunzhong; gribozavr@gmail.com; craig.topper@gmail.com; Robinson, Paul<br>
<b>Cc:</b> Bedwell, Greg; cfe-commits@lists.llvm.org<br>
<b>Subject:</b> Re: [PATCH] D17550: Adding doxygen comments to the LLVM intrinsics (part 6, popcntintrin.h)<o:p></o:p></span></p>
</div>
</div>
<p class="MsoNormal"><o:p> </o:p></p>
<div>
<p class="MsoNormal">Those are all compelling reasons for me. Let's go with whatever you and Dmitri think would be best for now. :)<o:p></o:p></p>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">-eric<o:p></o:p></p>
</div>
</div>
<p class="MsoNormal"><o:p> </o:p></p>
<div>
<div>
<p class="MsoNormal">On Wed, Feb 24, 2016 at 12:41 PM Romanova, Katya <<a href="mailto:Katya_Romanova@playstation.sony.com">Katya_Romanova@playstation.sony.com</a>> wrote:<o:p></o:p></p>
</div>
<blockquote style="border:none;border-left:solid #CCCCCC 1.0pt;padding:0in 0in 0in 6.0pt;margin-left:4.8pt;margin-right:0in">
<div>
<div>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Hello,</span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"> </span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">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.</span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"> </span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Before we start discussing the exact format, I want to make sure that we really want to change to
C-style doxygen comments. </span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Here are my not-so-strong arguments against it:</span><o:p></o:p></p>
<p style="margin-left:20.4pt"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">-</span><span style="font-size:7.0pt;color:#1F497D">
</span><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">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.</span><o:p></o:p></p>
<p style="margin-left:20.4pt"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">-</span><span style="font-size:7.0pt;color:#1F497D">
</span><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">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.</span><o:p></o:p></p>
<p style="margin-left:20.4pt"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">-</span><span style="font-size:7.0pt;color:#1F497D">
</span><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">C++ style doxygen comments are more pretty and readable compared to C-style comment (though it might be my subjective opinion).</span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"> </span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Let me know what you think.
</span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"> </span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">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.</span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"> </span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Katya.</span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"> </span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto"><a name="msg-f:1527089976323532509__MailEndCompos"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"> </span></a><o:p></o:p></p>
<div style="border:none;border-left:solid blue 1.5pt;padding:0in 0in 0in 4.0pt">
<div>
<div style="border:none;border-top:solid #B5C4DF 1.0pt;padding:3.0pt 0in 0in 0in">
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto"><b><span style="font-size:10.0pt;font-family:"Tahoma","sans-serif"">From:</span></b><span style="font-size:10.0pt;font-family:"Tahoma","sans-serif""> Eric Christopher [mailto:<a href="mailto:echristo@gmail.com" target="_blank">echristo@gmail.com</a>]
<br>
<b>Sent:</b> Tuesday, February 23, 2016 10:51 PM<br>
<b>To:</b> <a href="mailto:reviews%2BD17550%2Bpublic%2Bbc8ce213fd9db980@reviews.llvm.org" target="_blank">
reviews+D17550+public+bc8ce213fd9db980@reviews.llvm.org</a>; Romanova, Katya; Gao, Yunzhong;
<a href="mailto:gribozavr@gmail.com" target="_blank">gribozavr@gmail.com</a>; <a href="mailto:craig.topper@gmail.com" target="_blank">
craig.topper@gmail.com</a>; Robinson, Paul<br>
<b>Cc:</b> Bedwell, Greg; <a href="mailto:cfe-commits@lists.llvm.org" target="_blank">
cfe-commits@lists.llvm.org</a><br>
<b>Subject:</b> Re: [PATCH] D17550: Adding doxygen comments to the LLVM intrinsics (part 6, popcntintrin.h)</span><o:p></o:p></p>
</div>
</div>
</div>
</div>
</div>
<div>
<div>
<div style="border:none;border-left:solid blue 1.5pt;padding:0in 0in 0in 4.0pt">
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto"> <o:p></o:p></p>
<p>Yeah, we should be doing this. Nice catch Paul and Greg. <o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto"> <o:p></o:p></p>
<div>
<div>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto">On Tue, Feb 23, 2016, 10:34 PM Greg Bedwell <<a href="mailto:greg_bedwell@sn.scee.net" target="_blank">greg_bedwell@sn.scee.net</a>> wrote:<o:p></o:p></p>
</div>
<blockquote style="border:none;border-left:solid #CCCCCC 1.0pt;padding:0in 0in 0in 6.0pt;margin-left:4.8pt;margin-top:5.0pt;margin-right:0in;margin-bottom:5.0pt">
<p class="MsoNormal" style="mso-margin-top-alt:auto;margin-bottom:12.0pt">gbedwell added a subscriber: gbedwell.<br>
gbedwell added a comment.<br>
<br>
In <a href="http://reviews.llvm.org/D17550#360177" target="_blank">http://reviews.llvm.org/D17550#360177</a>, @probinson wrote:<br>
<br>
> One question I have, which shouldn't block this (as we've done several like this already):<br>
> Is is okay to be using C++ style comments in these headers?<br>
> (Is there a C-style comment that Doxygen recognizes?)<br>
<br>
<br>
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:<br>
<br>
/**<br>
<br>
- Diagnostic handler type.<br>
- \p severity defines the severity.<br>
- \p diag is the actual diagnostic.<br>
- The diagnostic is not prefixed by any of severity keyword, e.g., 'error: '.<br>
- \p ctxt is used to pass the context set with the diagnostic handler. *<br>
- \since LTO_API_VERSION=7 */<br>
<br>
-Greg<br>
<br>
<br>
Repository:<br>
rL LLVM<br>
<br>
<a href="http://reviews.llvm.org/D17550" target="_blank">http://reviews.llvm.org/D17550</a><br>
<br>
<o:p></o:p></p>
</blockquote>
</div>
</div>
</div>
</div>
</blockquote>
</div>
</div>
</div>
</body>
</html>