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