From 1cf942cb4f893690c430571295777f4f9de8ee95 Mon Sep 17 00:00:00 2001 From: Matthias Braun Date: Fri, 15 May 2015 03:34:01 +0000 Subject: [PATCH] Doxygen: Enable autobrief feature and update coding standards. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@237417 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/CodingStandards.rst | 29 +++++++++++++++-------------- docs/doxygen.cfg.in | 4 ++-- 2 files changed, 17 insertions(+), 16 deletions(-) diff --git a/docs/CodingStandards.rst b/docs/CodingStandards.rst index 8c8110d0332..498d76b04d8 100644 --- a/docs/CodingStandards.rst +++ b/docs/CodingStandards.rst @@ -247,8 +247,8 @@ tree. The standard header looks like this: //===----------------------------------------------------------------------===// /// /// \file - /// \brief This file contains the declaration of the Instruction class, which is - /// the base class for all of the VM instructions. + /// This file contains the declaration of the Instruction class, which is the + /// base class for all of the VM instructions. /// //===----------------------------------------------------------------------===// @@ -268,10 +268,10 @@ file is released under. This makes it perfectly clear what terms the source code can be distributed under and should not be modified in any way. The main body is a ``doxygen`` comment (identified by the ``///`` comment -marker instead of the usual ``//``) describing the purpose of the file. It -should have a ``\brief`` command that describes the file in one or two -sentences. Any additional information should be separated by a blank line. If -an algorithm is being implemented or something tricky is going on, a reference +marker instead of the usual ``//``) describing the purpose of the file. The +first sentence or a passage beginning with ``\brief`` is used as an abstract. +Any additional information should be separated by a blank line. If an +algorithm is being implemented or something tricky is going on, a reference to the paper where it is published should be included, as well as any notes or *gotchas* in the code to watch out for. @@ -320,10 +320,11 @@ Doxygen Use in Documentation Comments Use the ``\file`` command to turn the standard file header into a file-level comment. -Include descriptive ``\brief`` paragraphs for all public interfaces (public -classes, member and non-member functions). Explain API use and purpose in -``\brief`` paragraphs, don't just restate the information that can be inferred -from the API name. Put detailed discussion into separate paragraphs. +Include descriptive paragraphs for all public interfaces (public classes, +member and non-member functions). Don't just restate the information that can +be inferred from the API name. The first sentence or a paragraph beginning +with ``\brief`` is used as an abstract. Put detailed discussion into separate +paragraphs. To refer to parameter names inside a paragraph, use the ``\p name`` command. Don't use the ``\arg name`` command since it starts a new paragraph that @@ -343,8 +344,8 @@ A minimal documentation comment: .. code-block:: c++ - /// \brief Does foo and bar. - void fooBar(bool Baz); + /// Sets the xyzzy property to \p Baz. + void setXyzzy(bool Baz); A documentation comment that uses all Doxygen features in a preferred way: @@ -401,10 +402,10 @@ Correct: // In Something.h: - /// \brief An abstraction for some complicated thing. + /// An abstraction for some complicated thing. class Something { public: - /// \brief Does foo and bar. + /// Does foo and bar. void fooBar(); }; diff --git a/docs/doxygen.cfg.in b/docs/doxygen.cfg.in index 114c9d11c06..d8c4051e563 100644 --- a/docs/doxygen.cfg.in +++ b/docs/doxygen.cfg.in @@ -169,7 +169,7 @@ SHORT_NAMES = NO # description.) # The default value is: NO. -JAVADOC_AUTOBRIEF = NO +JAVADOC_AUTOBRIEF = YES # 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 @@ -177,7 +177,7 @@ JAVADOC_AUTOBRIEF = NO # requiring an explicit \brief command for a brief description.) # The default value is: NO. -QT_AUTOBRIEF = NO +QT_AUTOBRIEF = YES # The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a # multi-line C++ special comment block (i.e. a block of //! or /// comments) as -- 2.34.1