Guidelines for API documentation » History » Revision 2
Revision 1 (neels, 06/20/2017 01:55 AM) → Revision 2/25 (neels, 06/20/2017 01:58 AM)
h1. Guidelines for API documentation We use doxygen for API documentation, following these guidelines: Use the @/*!@ (Qt-style) doxygen markers. Since we are using the AUTOBRIEF feature, always end the first sentence with a full-stop "." to mark the end of the short description. This allows omitting the @\brief@ markers everywhere. Never rely on line breaks as semantic separation or to end a sentence, always use proper punctuation. The API doc may be rendered with different line breaks than in the source file. h2. File comments If a file contains a descriptive comment, this comment should be right at the start of the file, as a doxygen @\file@ section. The first sentence must be ended by a full stop "." to mark the end of the short description. The copyright notice shall not be part of such API doc file comment. <pre> /*! \file foo.c * Short description. */ /* * (C) 2017 ... Copyright not in a doxygen comment * license information */ </pre> or <pre> /*! \file foo.c * Short description. * * More information in multiple lines. */ /* * (C) 2017 ... */ </pre> h2. Groups Doxygen allows grouping elements: a group can include code elements and also entire files. This works by enclosing the items to be grouped between an opening and a closing marker: * A @\defgroup@ initially defines a group, this shall exist only once. * More items can be added using an @\addtogroup@ marker. * Both have to be closed by "@}". For example: <pre> /*! \defgroup groupname Short description of the group. * @{ */ struct type_that_belongs_to_group { ... }; void func_that_belongs_to_group() { ... } /*! @} */ </pre> and <pre> /*! \addtogroup groupname * @{ */ [...] /*! @} */ </pre> If a *file* should be added to a group, add a (possibly) second, short descriptionless @\file@ tag to the group start. To clearly mark that the purpose is to add to the group, do so within the same comment block: <pre> /*! \file foo.c * File's description. description */ /* * (C) ... */ /*! \addtogroup groupname * @{ * \file foo.c */ ... /*! @} */ </pre> The point is that we like to have a file's short description near the start of the file, to also serve us well when we're reading only the .h file. But to be included in a group, the doxygen group start must precede the @\file@ tag. Also, the doxygen group should rather not enclose @#include@ directives, to clearly exclude those from the group. Hence, the best way is to keep the file's actual description at the top of the file, and add a second descriptionless @\file@ with the group opening. A group may contain a short as well as a longer description. We often @\defgroup@ in a @.h@ file but keep the longer description in an @\addtogroup@ in a @.c@ file. Any @\file@ tags must follow *after* such description, or the description will be associated with the file instead of the group: @.h@ file: <pre> /*! \defgroup groupname Short description of the group. * @{ */ ... /*! @} */ </pre> @.c file: <pre> /*! \addtogroup groupname * @{ * Longer description of the group. * - contains a * - bullet list * * As well as a * * Code example * block * * All of which must not be below the directive adding this file to the group: * * \file foo.c */ [...] /*! @} */ </pre> Often, a file's description matches or is identical with a group's description. In that case, the file's description header comment can be omitted to avoid duplicating identical descriptions. <pre> /* * (C) 2017 ... */ /* \addtogroup group * @{ * Description... * * \file foo.c */ ... /* @} */ </pre>