<p dir="ltr">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">matze@braunis.de</a>> wrote:<br type="attribution"><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>
<br>
- Matthias<br>
<br>
> On May 5, 2015, at 5:04 PM, Adrian Prantl <<a href="mailto:aprantl@apple.com">aprantl@apple.com</a>> wrote:<br>
><br>
> Getting rid of all the distracting \brief comment markers in our header files would be great!<br>
> Note that we will also need to update our coding standards to no longer encourage them then.<br>
><br>
> -- adrian<br>
>> On May 3, 2015, at 9:08 PM, Justin Bogner <<a href="mailto:mail@justinbogner.com">mail@justinbogner.com</a>> wrote:<br>
>><br>
>> Matthias Braun <<a href="mailto:matze@braunis.de">matze@braunis.de</a>> writes:<br>
>>> We just had some discussion in the IRC channel and wondered whether it<br>
>>> would be a good idea to enable one of the doxygen autobrief options<br>
>>> for llvm:<br>
>>><br>
>>> JAVADOC_AUTOBRIEF<br>
>>> If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret<br>
>>> the first line (until the first dot) of a Javadoc-style comment as the<br>
>>> brief description. If set to NO, the Javadoc-style will behave just<br>
>>> like regular Qt-style comments (thus requiring an explicit @brief<br>
>>> command for a brief description.)<br>
>>><br>
>>> The default value is: NO.<br>
>>><br>
>>> QT_AUTOBRIEF<br>
>>> If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the<br>
>>> first line (until the first dot) of a Qt-style comment as the brief<br>
>>> description. If set to NO, the Qt-style will behave just like regular<br>
>>> Qt-style comments (thus requiring an explicit \brief command for a<br>
>>> brief description.)<br>
>>><br>
>>> The default value is: NO.<br>
>>><br>
>>><br>
>>> Seeing that the \brief commands are often missing and visually noisy<br>
>>> (IMO) this may improve our documentation and save us some typing in<br>
>>> the future.<br>
>><br>
>> FWIW, I can't see any downside to enabling this option. Adding \brief is<br>
>> redundant and hurts readability in the source, and the fact that we're<br>
>> inconsistent about it means the experience in the doxygen-generated html<br>
>> is often missing summaries for functions, which is annoying. Setting the<br>
>> autobrief option improves both of these problems.<br>
>><br>
>> +1.<br>
>><br>
>>> - Matthias<br>
>>> _______________________________________________<br>
>>> LLVM Developers mailing list<br>
>>> <a href="mailto:LLVMdev@cs.uiuc.edu">LLVMdev@cs.uiuc.edu</a>         <a href="http://llvm.cs.uiuc.edu" target="_blank">http://llvm.cs.uiuc.edu</a><br>
>>> <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev</a><br>
>> _______________________________________________<br>
>> LLVM Developers mailing list<br>
>> <a href="mailto:LLVMdev@cs.uiuc.edu">LLVMdev@cs.uiuc.edu</a>         <a href="http://llvm.cs.uiuc.edu" target="_blank">http://llvm.cs.uiuc.edu</a><br>
>> <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev</a><br>
><br>
><br>
> _______________________________________________<br>
> LLVM Developers mailing list<br>
> <a href="mailto:LLVMdev@cs.uiuc.edu">LLVMdev@cs.uiuc.edu</a>         <a href="http://llvm.cs.uiuc.edu" target="_blank">http://llvm.cs.uiuc.edu</a><br>
> <a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev</a><br>
<br>
<br>
_______________________________________________<br>
LLVM Developers mailing list<br>
<a href="mailto:LLVMdev@cs.uiuc.edu">LLVMdev@cs.uiuc.edu</a>         <a href="http://llvm.cs.uiuc.edu" target="_blank">http://llvm.cs.uiuc.edu</a><br>
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev</a><br>
</blockquote></div>