DocCheck

目标

我们一直希望确保代码库中的每份知识都有一个单一、明确、权威的表示。然而，有时违反这一原则反而能提高软件项目的整体质量。例如，当我们编写包含示例代码片段的文档时，最好能为其编写测试——但是，如果这样做，相同的代码示例将同时存在于文档和测试中！这种知识的重复会带来实际的不利后果——当文档更新为新示例时，测试就会过时。此外，只有通过人工检查才能发现同一知识（例如代码示例）多个副本之间的差异。

在这种情况下，为了以可强制执行的方式建立单一的事实来源，我们可以求助于 DocCheck 工具。简而言之，DocCheck 会强制执行用户在代码库中文本工件之间指定的各种一致性约束。文本工件可以是：

• 文档中的章节
• 文件的内容
• 命令执行的输出
• …

具体来说，DocCheck 允许我们精确地指定一个文本工件是如何从另一个文本工件派生出来的。然后，我们的软件测试基础设施会解析和验证此类规范，以确保派生的文本工件与原始文本工件之间的一致性。这种整体工作流程提供了一种可强制执行的方式，可以在代码库中建立单一、明确且权威的知识表示。

指令

指令可用于将派生文本工件和原始文本工件之间的关系传达给 DocCheck。DocCheck 将根据规范执行一致性约束检查。本节将详细解释受支持的指令。

目前，指令可以在 Markdown 文件中或独立的 DocCheck 配置文件（以 .dc 后缀结尾的文件）中指定。对于 Markdown 文件，请使用以下语法指定指令：

[{directive}]: <> ({configuration})

对于独立的 DocCheck 配置文件，请使用以下语法：

{directive}({configuration})

其中 {directive} 是指令的名称，{configuration} 表示此指令的特定参数。通常，指令配置使用 Python 字典字面量表示，其中支持的配置参数名称作为键，所需配置状态作为值。

每个指令都有单独的特殊简写。

same-as-file（与文件相同）:

使用 same-as-file 指令可确保此指令后的代码部分与源文件相同。这主要很有用，因为直接测试文档中的代码片段通常是不可能的。然而，可以使用代码片段内容的精确副本编写单元测试。我们可以使用 same-as-file 指令来确保代码片段始终与其在某些单元测试中使用的副本相同。

same-as-file 指令支持方便的简写配置格式，其中指令配置可以使用要检查的参考文件名完全指定。例如，要确保代码片段与经过单元测试的文件 reference.cpp 相同，请使用文档片段中所示的以下指令：

same-as-file: <> ({“ref”: “docs/doc_check/test/same-as-file/simple/README.md”, “skip-ref”: 2})

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

[same-as-file]: <> (reference.cpp)
```cpp
#include<iostream>

using namespace std;

int main() {
    cout<<"Hello World";
    return 0;
}
```

在指令配置的规范形式（作为 Python 字典字面量）中，此指令支持以下参数：

ref (字符串)：要检查的参考文件。

skip-doc (整数)：检查文档时要跳过的行数。

skip-ref (整数)：扫描参考文件时要跳过的行数。

例如，要确保以下代码片段与经过单元测试的文件 reference.cpp 相同，但文档中使用的代码的前 2 行和参考文件中使用的代码的前 3 行除外，可以使用以下指令配置：

same-as-file: <> ({“ref”: “docs/doc_check/test/same-as-file/skip-doc-ref/README.md”, “skip-ref”: 2})

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

[same-as-file]: <> ({"ref": "reference.cpp", "skip-doc": 2, "skip-ref": 3})
```cpp
// First line unique to documentation
// Second line unique to documentation
#include<iostream>

using namespace std;

int main() {
    cout<<"Hello World";
    return 0;
}
```

file-same-as-stdout（文件与标准输出相同）

使用 file-same-as-stdout 可确保文件内容与执行命令的输出相同。此指令支持以下参数：

file (字符串)：要比较的文件。

cmd (List[str])：命令（表示为命令组件列表），例如 ["ls", "-l"]。

例如，要确保文件 test.in 的内容

dog

与命令执行 echo dog 的输出完全相同，可以使用以下指令：same-as-file: <> (docs/doc_check/test/file-same-as-stdout/success/test.in.dc)

file-same-as-stdout({"file": "test.in", "cmd": ["echo", "dog"]})