为 Boost 编写文档文档结构 |
Boost 不需要任何特定的文档结构。但是，有一些重要的考虑因素会影响内容和结构。例如，许多 Boost 库最终会被提议纳入 C++ 标准，因此最初用适合纳入标准格式的文本来编写它们可能会有所帮助。此外，Boost 库文档通常可以通过万维网访问，包括搜索引擎，因此上下文对每个页面都很重要。最后，Boost 库应提供额外的文档，例如介绍、教程、示例和原理内容。考虑到这些因素，我们为 Boost 库文档建议以下指南。
C++ 标准要求的文档结构是描述库技术规范的有效方法。尽管该格式简洁，但许多 Boost 用户都熟悉它，并且比大多数临时格式精确得多。以下描述基于标准 §17.3。（请注意，虽然最终的标准提案必须包含完整的“标准语”措辞，但委员会不会为您完成，Boost 库文档不需要达到该详细程度。）
每个文档包含以下元素（如适用）(1)
摘要提供了类别的概要，并介绍了第一级子条款。每个子条款也提供摘要，列出了子条款中指定的头文件以及每个头文件中提供的库实体。
标记为“注意：”或“示例：”的段落是信息性的，其他段落是规范性的。
摘要和详细规范的呈现顺序为
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 复制）