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
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
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>