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