[LLVMdev] Doxygen: enable autobrief?

[Matthias Braun]

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.

- Matthias

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