[LLVMdev] Doxygen: enable autobrief?

[Rafael Espíndola]

I am all for not having to add \brief. The more readable the comments are
for someone not using doxygen the better.
On May 8, 2015 2:06 PM, "Matthias Braun" <matze at braunis.de> wrote:

> 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
>
>
> _______________________________________________
> LLVM Developers mailing list
> LLVMdev at cs.uiuc.edu         http://llvm.cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20150522/acca740b/attachment.html>