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（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（字符串）：要比较的文件。

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