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 (string): 要检查的参考文件。

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

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

例如，为了确保以下代码片段与经过单元测试的文件 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 (string): 要比较的文件。

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"]})