为 Boost 编写文档

文档结构

引言

符合标准的文档

文档元素

摘要

要求

详细规范

引用标准 C++ 库

引用标准 C 库

其他约定

类型描述

更多信息

函数语义元素解释

要求（Requires）

效果（Effects）

后置条件（Postconditions）

返回值（Returns）

抛出（Throws）

复杂度（Complexity）

原理（Rationale）

Web 参考文档

脚注

引言

Boost 不要求任何特定的文档结构。但是，有一些重要的考虑因素会影响内容和结构。例如，许多 Boost 库最终会被提议纳入 C++ 标准，因此最初编写的文本适合纳入标准可能有所帮助。此外，Boost 库文档通常通过万维网访问，包括通过搜索引擎，因此上下文对于每个页面通常都很重要。最后，Boost 库应提供额外的文档，例如介绍、教程、示例和原理内容。考虑到这些因素，我们建议以下 Boost 库文档的指南。

符合标准的文档

C++ 标准所需的文档结构是描述库技术规范的有效方法。虽然简洁，但这种格式对于许多 Boost 用户来说都很熟悉，并且比大多数临时格式更精确。以下描述基于标准的 §17.3。（请注意，虽然最终的标准提案必须包括完整的标准措辞，委员会不会为您完成，但 Boost 库文档不要求达到这种详细程度。）

文档元素

每个文档都包含以下元素（如适用）(1)

• 摘要
• 要求
• 详细规范
• 引用标准 C++ 库
• 引用标准 C 库

摘要

摘要提供了类别的概要，并介绍了第一级子条款。每个子条款也提供摘要，列出子条款中指定的头文件和每个头文件中提供的库实体。

标记为“注意(Note(s):)”或“示例(Example(s):)”的段落是信息性的，其他段落是规范性的。

摘要和详细规范按以下顺序呈现

• 宏（Macros）
• 值（Values）
• 类型（Types）
• 类（Classes）
• 函数（Functions）
• 对象（Objects）

要求

该库可以由 C++ 程序扩展。每个子句（如适用）描述了此类扩展必须满足的要求。此类扩展通常是以下之一

• 模板参数
• 派生类
• 满足接口约定的容器、迭代器和/或算法

接口约定要求尽可能笼统地陈述。它不是说“class X 必须定义一个成员函数 operator++()”，而是要求“对于 class X 的任何对象 x，都定义了 ++x”。也就是说，该运算符是否为成员是未指定的。

要求以明确定义的表达式来陈述，这些表达式定义了满足要求的类型的有效项。对于每组要求，都有一个表格，其中指定了有效表达式的初始集合及其语义。任何使用这些要求的通用算法都根据其形式类型参数的有效表达式进行描述。

模板参数要求有时通过名称引用。

在某些情况下，语义要求以 C++ 代码的形式呈现。此类代码旨在将一个构造与另一个构造等价地规范，而不一定作为构造必须实现的方式。(2)

详细规范

每个详细规范都包含以下元素

• 名称和简短描述
• 概要（类定义或函数原型，如适用）
• 对模板参数的限制（如果有）
• 类不变量的描述
• 函数语义的描述

类成员函数的描述遵循以下顺序（如适用）(3)

• 构造函数和析构函数
• 复制和赋值函数
• 比较函数
• 修改器函数
• 观察器函数
• 运算符和其他非成员函数

函数语义的描述包含以下元素（如适用）(4):

要求（Requires）： 调用该函数的前提条件

效果（Effects）： 该函数执行的操作

后置条件（Postconditions）： 该函数建立的可观察的结果

返回值（Returns）： 对该函数返回的值的描述

抛出（Throws）： 该函数抛出的任何异常，以及导致该异常的条件

复杂度（Complexity）： 函数的时间和/或空间复杂度

原理（Rationale）： 函数的设计或存在的原因

库子句中指定的复杂度要求是上限，提供更好复杂度保证的实现满足要求。

引用 C++ 标准库

引用 C 标准库

其他约定

这些约定用于描述实现定义的类型和成员函数。

类型描述

“要求（Requirements）”子句可以描述用于指定对模板参数约束的名称。

更多信息

函数语义元素解释

上面的函数语义元素描述直接取自 C++ 标准，并且非常简洁。以下是对每个元素的更详细解释。

请注意使用 <code> ... </code> 字体标签来区分实际 C++ 用法和英文散文。

要求（Requires）

调用函数的前提条件，通常表示为谓词。最常见的前提条件是对参数值的要求，通常以 C++ 表达式的形式出现。例如，

 
void limit( int * p, int min, int max );

要求（Requires）： p != 0 && min <= max

C++ 语言规则已经强制执行的要求（例如参数的类型）不会在“要求（Requires）”段落中重复。

效果（Effects）

函数执行的操作，用散文或 C++ 描述。用散文描述通常对实现者限制较少，但通常不如 C++ 代码精确。

如果在其他元素（尤其是后置条件、返回值或抛出）中指定了效果，则不会在效果段落中描述。只有一个描述确保只有一个规范，从而消除了发散的风险。

后置条件（Postconditions）

函数的可观察结果，例如变量的值。后置条件通常表示为在函数完成后为真的谓词，形式为 C++ 表达式。例如

 
void make_zero_if_negative( int & x );

后置条件（Postcondition）： x >= 0

返回值（Returns）

函数返回的值，通常以 C++ 表达式的形式出现。例如

int sum( int x, int y );

返回值（Returns）： x + y

仅指定返回值；类型已由 C++ 语言规则决定。

抛出（Throws）

指定抛出的异常类型，以及导致抛出异常的条件。例如，std::basic_string 类指定

 
void resize(size_type n, charT c);

抛出（Throws）： 如果 n > max_size()，则抛出 length_error。

复杂度（Complexity）

指定函数的时间和/或空间复杂度通常是不希望的，因为它过度限制了实现者并且很难正确指定。因此，复杂度通常最好留作实现质量问题。

但是，如果符合规范的实现之间的性能差异很大，则库组件可能会变得实际上不可移植。容器就是一个主要例子。在这种情况下，指定复杂度就变得值得了。

复杂度通常以广义的 “大O”表示法指定。

原理（Rationale）

指定函数的设计或存在的原因通常可以帮助用户深入了解库的设计方式。更重要的是，它可以帮助防止“修复”在库成熟过程中实际上没有损坏的东西。

Web 参考文档

Boost 库文档通常通过 Web 访问。使用搜索引擎，可能会查看参考内容深处的页面，而没有任何进一步的上下文。因此，在每个页面上添加额外的上下文（例如以下内容）会有所帮助

• 描述封闭的命名空间或使用完全限定的标识符。
• 为每个类型或函数记录所需的头文件。
• 链接到相关的教程信息。
• 链接到相关的示例代码。
• 包括库名称。
• 包括到文档开头的导航元素。

考虑描述在搜索引擎中的有效性也很有用。简洁或神秘的描述不太可能帮助好奇的人找到相关的函数或类型。

脚注

(1) 为了节省空间，省略了不适用于子句的项目。例如，如果一个子句没有指定任何要求，则不会有“要求（Requirements）”子句。

(2) 虽然在某些情况下，该代码明确是最佳实现。

(3) 为了节省空间，省略了不适用于类的项目。例如，如果一个类没有指定任何比较函数，则不会有“比较函数”子句。

(4) 为了节省空间，省略了不适用于函数的项目。例如，如果一个函数没有指定任何前提条件，则不会有“要求（Requires）”段落。

修订2006年12月4日

版权所有 © 2001 William E. Kempf

根据 Boost 软件许可证 1.0 版分发。（请参阅随附文件 LICENSE_1_0.txt 或在 https://boost.ac.cn/LICENSE_1_0.txt 处复制）