Boost 不要求任何特定的文档结构。然而，有一些重要的考虑因素会影响内容和结构。例如，许多 Boost 库最终会被提议纳入 C++ 标准，因此最初编写它们时使用适合纳入标准的文本可能会有所帮助。此外，Boost 库文档通常通过万维网访问，包括通过搜索引擎访问，因此上下文对于每个页面通常都很重要。最后，Boost 库应提供额外的文档，例如介绍性、教程、示例和原理内容。考虑到这些，我们为 Boost 库文档提出以下指南。
C++ 标准要求的文档结构是描述库的技术规范的有效方法。虽然简洁，但这种格式为许多 Boost 用户所熟悉，并且比大多数临时格式更精确。以下描述基于标准的 §17.3。（请注意，虽然最终的标准提案必须包括完整的 standardese 措辞，委员会不会为您做这件事，但 Boost 库文档不需要这种详细程度。）
每个文档都包含以下元素（如适用）(1)
摘要提供了类别的概要，并介绍了第一级子条款。每个子条款也提供一个摘要，列出子条款中指定的头文件以及每个头文件中提供的库实体。
标有“Note(s):”或“Example(s):”的段落是信息性的，其他段落是规范性的。
摘要和详细规范按以下顺序呈现
库可以通过 C++ 程序扩展。每个条款（如适用）描述了此类扩展必须满足的要求。此类扩展通常是以下之一
接口约定要求尽可能笼统地说明。接口要求“对于 class X 的任何对象 x，都定义了 ++x”，而不是声明“class X 必须定义成员函数 operator++()”。也就是说，运算符是否是成员是未指定的。
要求以明确定义的表达式形式陈述，这些表达式定义了满足要求的类型的有效术语。对于每组要求，都有一个表格，其中指定了有效表达式的初始集合及其语义。任何使用这些要求的通用算法都根据其形式类型参数的有效表达式来描述。
模板参数要求有时通过名称引用。
在某些情况下，语义要求以 C++ 代码的形式呈现。此类代码旨在作为一种构造与另一种构造等效的规范，而不一定是构造必须实现的方式。(2)
详细规范各自包含以下元素
类成员函数的描述遵循以下顺序（如适用）(3)
库条款中指定的复杂度要求是上限，提供更好复杂度保证的实现满足要求。
这些约定用于描述实现定义的类型和成员函数。
Requirements 子条款可以描述用于指定模板参数约束的名称。
上面的函数语义元素描述 直接取自 C++ 标准，非常简洁。以下是每个元素的更详细解释。
请注意使用 <code> ... </code> 字体标签来区分实际的 C++ 用法和英文散文。
调用函数的前提条件，通常表示为谓词。最常见的前提条件是对参数值的要求，通常以 C++ 表达式的形式表示。例如，
void limit( int * p, int min, int max );
p != 0 && min <= maxC++ 语言规则已经强制执行的要求（例如参数的类型）不会在 Requires 段落中重复。
函数执行的操作，以散文或 C++ 描述。以散文形式描述通常对实现者限制较少，但通常不如 C++ 代码精确。
如果效果在其他元素之一中指定，特别是postconditions、returns 或 throws，则它也不会在 effects 段落中描述。只有一个描述可以确保只有一个规范，从而消除分歧的风险。
函数的可观察结果，例如变量的值。后置条件通常表示为在函数完成后为真的谓词，以 C++ 表达式的形式表示。例如
void make_zero_if_negative( int & x );
x >= 0函数返回的值，通常以 C++ 表达式的形式表示。例如
int sum( int x, int y );
x + y仅指定返回值；类型已由 C++ 语言规则规定。
指定抛出的异常类型和导致抛出异常的条件。例如，std::basic_string 类指定
void resize(size_type n, charT c);
n > max_size()，则抛出 length_error。指定函数的时间和/或空间复杂度通常是不希望的，因为它过度约束了实现者，并且难以正确指定。因此，复杂度通常最好留作实现质量问题。
但是，如果符合规范的实现之间性能差异很大，则库组件可能会变得实际上不可移植。容器就是一个典型的例子。在这些情况下，指定复杂度变得有价值。
复杂度通常以广义的 “大 O”符号 指定。
指定函数设计或存在的原理通常可以让用户深入了解库的设计方式。更重要的是，它可以帮助防止在库成熟时“修复”实际上没有损坏的东西。
Boost 库文档通常通过万维网访问。使用搜索引擎，可以查看参考内容深处的页面，而无需任何进一步的上下文。因此，在每个页面上添加额外的上下文很有帮助，例如以下内容
考虑描述在搜索引擎中的有效性也很有用。简洁或隐晦的描述不太可能帮助好奇的人找到相关的函数或类型。
修订2006 年 12 月 4 日
版权所有 © 2001 William E. Kempf
根据 Boost 软件许可协议 1.0 版分发。（请参阅随附文件 LICENSE_1_0.txt 或在 https://boost.ac.cn/LICENSE_1_0.txt 复制）