<html><head><meta http-equiv="Content-Type" content="text/html charset=utf-8"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class=""><br class=""></div><div class=""><br class=""></div><div class="">- Matthias</div><div class=""><br class=""></div><div><blockquote type="cite" class=""><div class="">On May 26, 2015, at 3:48 PM, Chandler Carruth <<a href="mailto:chandlerc@google.com" class="">chandlerc@google.com</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><div dir="ltr" class="">So, I'd love to not have to write '\brief' but that's not what this gives us sadly.<br class=""><br class="">The behavior of autobrief is that the brief snippet stops at the first '.' in the text. It doesn't matter if that '.' is part of code or anything else.</div></div></blockquote><div class="">Yes, I also find the autobrief setting annoying that it stops at the first dot and not takes the first paragraph. In any way I documented this behaviour in the llvm coding standards.</div><div class=""><br class=""></div><blockquote type="cite" class=""><div class=""><div dir="ltr" class=""><div class=""><br class=""></div><div class="">The behavior of the '\brief' command is that the paragraph it marks is the brief comment, and the detailed one starts with the next paragraph.</div><div class=""><br class=""></div><div class="">I want the second behavior, and *not* the first. Turning on the autobrief setting and encouraging its use will just cause us to have bad brief comments in the doxygen and easy to read source code. =/ I'd actually rather we write the (annoying and ugly) '\brief' command in the comments until the tools for extracting this are fixed to do something more sensible.</div></div></div></blockquote><div><br class=""></div><div>But there is also a problem with the current setting: Several people don't care or forget to add \brief commands. In fact I'm pretty sure enabling autobrief fixes more places where \brief was accidentally forgotten than we would risk to have bad brief sections because of unintuitive autobrief behaviour. In any both problems can be easily fixed once noticed.</div><div><br class=""></div><div>My main motivation to do this change: While I do care a lot about well documented interfaces; I do not care so much about the generated doxygen html pages. I'd dare to say the majority of llvm developers only looks at the headers and not the generated pages. So aiming for less \brief noise in the headers is a good thing.</div><div><br class=""></div><div>- Matthias</div><br class=""><blockquote type="cite" class=""><div class=""><br class=""><div class="gmail_quote">On Fri, May 22, 2015 at 12:48 PM Matthias Braun <<a href="mailto:matze@braunis.de" class="">matze@braunis.de</a>> wrote:<br class=""><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word" class=""><div class="">Hey,</div><div class=""><br class=""></div><div class="">I probably should have mentioned it in this thread: I enabled autobrief in r237417.</div></div><div style="word-wrap:break-word" class=""><div class=""><br class=""></div><div class="">- Matthias</div></div><div style="word-wrap:break-word" class=""><br class=""><div class=""><blockquote type="cite" class=""><div class="">On May 22, 2015, at 10:36 AM, Rafael Espíndola <<a href="mailto:rafael.espindola@gmail.com" target="_blank" class="">rafael.espindola@gmail.com</a>> wrote:</div><br class=""><div class=""><p dir="ltr" class="">I am all for not having to add \brief. The more readable the comments are for someone not using doxygen the better. </p>
<div class="gmail_quote">On May 8, 2015 2:06 PM, "Matthias Braun" <<a href="mailto:matze@braunis.de" target="_blank" class="">matze@braunis.de</a>> wrote:<br type="attribution" class=""><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">So far I've heard no objections, I'll wait a few more days and then change the doxygen configuration and the recommendations in the coding standards. I do not plan to remove any of the existing \brief comments though.<br class="">
<br class="">
- Matthias<br class="">
<br class="">
> On May 5, 2015, at 5:04 PM, Adrian Prantl <<a href="mailto:aprantl@apple.com" target="_blank" class="">aprantl@apple.com</a>> wrote:<br class="">
><br class="">
> Getting rid of all the distracting \brief comment markers in our header files would be great!<br class="">
> Note that we will also need to update our coding standards to no longer encourage them then.<br class="">
><br class="">
> -- adrian<br class="">
>> On May 3, 2015, at 9:08 PM, Justin Bogner <<a href="mailto:mail@justinbogner.com" target="_blank" class="">mail@justinbogner.com</a>> wrote:<br class="">
>><br class="">
>> Matthias Braun <<a href="mailto:matze@braunis.de" target="_blank" class="">matze@braunis.de</a>> writes:<br class="">
>>> We just had some discussion in the IRC channel and wondered whether it<br class="">
>>> would be a good idea to enable one of the doxygen autobrief options<br class="">
>>> for llvm:<br class="">
>>><br class="">
>>> JAVADOC_AUTOBRIEF<br class="">
>>> If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret<br class="">
>>> the first line (until the first dot) of a Javadoc-style comment as the<br class="">
>>> brief description. If set to NO, the Javadoc-style will behave just<br class="">
>>> like regular Qt-style comments (thus requiring an explicit @brief<br class="">
>>> command for a brief description.)<br class="">
>>><br class="">
>>> The default value is: NO.<br class="">
>>><br class="">
>>> QT_AUTOBRIEF<br class="">
>>> If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the<br class="">
>>> first line (until the first dot) of a Qt-style comment as the brief<br class="">
>>> description. If set to NO, the Qt-style will behave just like regular<br class="">
>>> Qt-style comments (thus requiring an explicit \brief command for a<br class="">
>>> brief description.)<br class="">
>>><br class="">
>>> The default value is: NO.<br class="">
>>><br class="">
>>><br class="">
>>> Seeing that the \brief commands are often missing and visually noisy<br class="">
>>> (IMO) this may improve our documentation and save us some typing in<br class="">
>>> the future.<br class="">
>><br class="">
>> FWIW, I can't see any downside to enabling this option. Adding \brief is<br class="">
>> redundant and hurts readability in the source, and the fact that we're<br class="">
>> inconsistent about it means the experience in the doxygen-generated html<br class="">
>> is often missing summaries for functions, which is annoying. Setting the<br class="">
>> autobrief option improves both of these problems.<br class="">
>><br class="">
>> +1.<br class="">
>><br class="">
>>> - Matthias<br class="">
>>> _______________________________________________<br class="">
>>> LLVM Developers mailing list<br class="">
>>> <a href="mailto:LLVMdev@cs.uiuc.edu" target="_blank" class="">LLVMdev@cs.uiuc.edu</a> <a href="http://llvm.cs.uiuc.edu/" target="_blank" class="">http://llvm.cs.uiuc.edu</a><br class="">
>>> <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev" target="_blank" class="">http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev</a><br class="">
>> _______________________________________________<br class="">
>> LLVM Developers mailing list<br class="">
>> <a href="mailto:LLVMdev@cs.uiuc.edu" target="_blank" class="">LLVMdev@cs.uiuc.edu</a> <a href="http://llvm.cs.uiuc.edu/" target="_blank" class="">http://llvm.cs.uiuc.edu</a><br class="">
>> <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev" target="_blank" class="">http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev</a><br class="">
><br class="">
><br class="">
> _______________________________________________<br class="">
> LLVM Developers mailing list<br class="">
> <a href="mailto:LLVMdev@cs.uiuc.edu" target="_blank" class="">LLVMdev@cs.uiuc.edu</a> <a href="http://llvm.cs.uiuc.edu/" target="_blank" class="">http://llvm.cs.uiuc.edu</a><br class="">
> <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev" target="_blank" class="">http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev</a><br class="">
<br class="">
<br class="">
_______________________________________________<br class="">
LLVM Developers mailing list<br class="">
<a href="mailto:LLVMdev@cs.uiuc.edu" target="_blank" class="">LLVMdev@cs.uiuc.edu</a> <a href="http://llvm.cs.uiuc.edu/" target="_blank" class="">http://llvm.cs.uiuc.edu</a><br class="">
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev" target="_blank" class="">http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev</a><br class="">
</blockquote></div>
_______________________________________________<br class="">LLVM Developers mailing list<br class=""><a href="mailto:LLVMdev@cs.uiuc.edu" target="_blank" class="">LLVMdev@cs.uiuc.edu</a> <a href="http://llvm.cs.uiuc.edu/" target="_blank" class="">http://llvm.cs.uiuc.edu</a><br class=""><a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev" target="_blank" class="">http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev</a><br class=""></div></blockquote></div><br class=""></div>_______________________________________________<br class="">
LLVM Developers mailing list<br class="">
<a href="mailto:LLVMdev@cs.uiuc.edu" target="_blank" class="">LLVMdev@cs.uiuc.edu</a> <a href="http://llvm.cs.uiuc.edu/" target="_blank" class="">http://llvm.cs.uiuc.edu</a><br class="">
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev" target="_blank" class="">http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev</a><br class="">
</blockquote></div>
_______________________________________________<br class="">LLVM Developers mailing list<br class=""><a href="mailto:LLVMdev@cs.uiuc.edu" class="">LLVMdev@cs.uiuc.edu</a> <a href="http://llvm.cs.uiuc.edu" class="">http://llvm.cs.uiuc.edu</a><br class=""><a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev" class="">http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev</a><br class=""></div></blockquote></div><br class=""></body></html>