[LLVMdev] Doxygen: enable autobrief?

[Matthias Braun]

Hey,

I probably should have mentioned it in this thread: I enabled autobrief in r237417.

- Matthias

> On May 22, 2015, at 10:36 AM, Rafael Espíndola <rafael.espindola at gmail.com> wrote:
> 
> 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 <mailto: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 <mailto: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 <mailto:mail at justinbogner.com>> wrote:
> >>
> >> Matthias Braun <matze at braunis.de <mailto: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 <mailto:LLVMdev at cs.uiuc.edu>         http://llvm.cs.uiuc.edu <http://llvm.cs.uiuc.edu/>
> >>> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev <http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev>
> >> _______________________________________________
> >> LLVM Developers mailing list
> >> LLVMdev at cs.uiuc.edu <mailto:LLVMdev at cs.uiuc.edu>         http://llvm.cs.uiuc.edu <http://llvm.cs.uiuc.edu/>
> >> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev <http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev>
> >
> >
> > _______________________________________________
> > LLVM Developers mailing list
> > LLVMdev at cs.uiuc.edu <mailto:LLVMdev at cs.uiuc.edu>         http://llvm.cs.uiuc.edu <http://llvm.cs.uiuc.edu/>
> > http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev <http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev>
> 
> 
> _______________________________________________
> LLVM Developers mailing list
> LLVMdev at cs.uiuc.edu <mailto:LLVMdev at cs.uiuc.edu>         http://llvm.cs.uiuc.edu <http://llvm.cs.uiuc.edu/>
> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev <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/1dc0b965/attachment.html>