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