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