🔗 Doxygen 文档指南和标准

这是一个关于标准 Doxygen 文档格式和模板的**提案**。目的是让文档编写者能够专注于文档内容，而不是 Doxygen 的格式和语义，并帮助他们不干扰代码的可读性。

🔗 需要记录的实体

有几种类型的实体需要记录：**类型**、**变量**（全局变量和成员变量）、**类**、**类方法**、**函数**和**组件**。

• 类型
  如果可能，应该只用一行简短的描述来记录。
• 变量
  应该在声明点进行记录。成员变量在类内部，公共全局变量在 .h 文件中，私有全局变量在 .cc 文件中。
• 类应该在其各自的头文件中，在其声明之前进行记录。
• 类方法应该在声明它们的类内部进行记录。参数名称必须与 .cc 文件中使用的完全相同。
• 函数应该在声明它们的 .h 文件中进行记录。只在 .cc 文件中*私有*声明的函数应该在实现文件中，在其主体之前进行记录。参数名称必须与 .cc 文件中使用的完全相同。
• 组件包含附加的文档信息，例如组件 API 对象组、组件状态流程图等，这些文档有更复杂的要求。请参阅下文。

🔗 文档格式

使用 C 风格的注释，每行以星号开头，并使用 LaTeX 风格的命令。每个块应该分为几个部分，用空行分隔。每个块以简短的描述开始。例如：

    /** Brief description goes here (single-line, less than 78 chars)
     *
     * Long description. May span multiple lines. Avoid repeating the brief
     * description if possible, leave empty if the brief description is
     * sufficient to document the documented entity's purpose, preconditions,
     * side-effects etc.
     *
     * \command arguments etc. May span multiple lines
     * \command arguments group commands by type
     * \othercommand arguments etc.
     *
     * \yetanothercommand some entities may require more than one documentation block
     */

🔗 模板

所有命令都是可选的，但当使用时，请按照此处所示的方式分组。方括号表示可选参数，省略号 (...) 表示可选重复。**不要**使用 HTML 格式代码（或任何类型的格式代码）。坚持基本原则。

唯一可能使用的特殊代码是列表，其语法是：

 - unordered list item 1
 - unordered list item 2
 - unordered list item 3

或者

 -# numbered list item 1
 -# numbered list item 2
 -# numbered list item 3

🔗 类文档模板

    /** Class handling activity X
     *
     * This class handles activity highly-critical asynchronous activity X.
     * It needs to be registered in registry Foo from the main entry point X.
     * After that it will respond to events Bar and possibly invoke Gazonk.
     *
     * \ingroup ParentGroupLabel
     */

🔗 函数 / 类方法文档模板

    /** Function handling activity Y
     *
     * This function does activity Y, requiring blah blah blah.
     * End with an empty line.
     * [\note particular informations]
     *
     * \param paramName paramDesc
     * ...
     * \return returnValueDesc
     * \retval special-return-value return-value-desc
     * ...
     * \throw exceptionName exceptionCondition
     * ...
     * \pre precondition(s)
     * ...
     * \post postcondition(s)
     * ...
     *
     * \warning bad behaviour in unexpected cases
     * ...
     * \bug unexpected behaviour when
     * ...
     * \deprecated from version X, use otherCall instead
     * \todo if the function needs changing
     * ...
     * \see otherReferences
     */

🔗 组件文档

为简单起见，在对组件进行 Features/SourceLayout 更改之前，不值得做大量的组件文档工作。在此之后，将适用以下规定……

Squid 中的每个组件都将拥有自己的库。组件的文档应包含在该库的 src/子文件夹中。必须包含的部分有：

• API
  这是组件*组*的定义，用于汇集提供的类、函数和全局变量。接着是库 API 的概述及其使用方法。不要包含特定函数的详细信息，它们的文档会涵盖。
• 组件流程
  对该组件的状态流程的期望进行高层次的抽象描述，以及对内部组的定义。

🔗 组件文档模板

组件文档比大多数文档都要长且详细，可以使用 Doxygen 的详细格式以及章节和标题等功能来编写。这是一个组件模板：

    /**
    \defgroup ComponentName Component Name
    
    \defgroup ComponentNameAPI Component Name API
    \ingroup ComponentName
    
    \section Terminology Terminology
    
    - \b Foo: this is a glossary section for component-specific terms.
    - \b Blah: a blah is a fake word used in this documentation.
    - \b Foo:  another fake word, usually representing something
    
    
    \section API API overview
    
    Very abstracted overview description of the API.
    Should be enough for someone to understand the API and be able to find
    the specific functions they want for more detailed documentation.
    
    Do not repeat or go into details covered by any function documentation.
    
    
    \defgroup ComponentNameInternals Component Name Internals
    \ingroup ComponentName
    
    \section StateFlow State Flow
    
    Detailed description of any state low that may occur.
    For example the protocol components contain a high-level sequence
    of request states and the output reply states that those requests may become.
    This section may even have links to flow diagrams and other more complicated stuff
    
    It's a long description. May span multiple lines and paragraphs. Avoid repeating stuff
    if possible use references or object by exact Class::someMethod(char *p) declaration
    of if you really have to use \include Class::someMethod(char *p) to pull that objects
    docs in cleanly.
    
     */

所有这些都将写在一个 *.dox 文件中，位于组件子文件夹内。

导航：网站搜索，网站页面，分类，🔼 向上