スクリプトによるソースツリーのチェック¶

警告

このセクションは古くなっています。記載されているいくつかのチェックは、:issue:`3288`および関連する問題で、現在実行されていません、または非推奨となっています。

現在、「docs/doxygen/」に存在するPythonスクリプトのセットは、ソースツリーのさまざまな側面における一貫性をチェックします。これらのスクリプトは、さまざまなソースから抽象的なソースツリーの表現を生成することに基づいて動作します。

ソースツリー内のファイルのリスト（ソースツリー全体のレイアウトのため）
インストールされているヘッダーの一覧（生成されたビルドシステムから抽出）
git attributes (特定のチェックの範囲を制限するために使用)
Doxygen XMLドキュメント:
- ドキュメントされたヘッダーやその他の要素の公/私に関する情報について
- 実際のドキュメントで定義された要素を確認し、一貫性を検証するために
GROMACS ソースツリーのレイアウトに関する、ハードコーディングされた知識

この表現は、さまざまな目的で使用されます。

Doxygenドキュメントの要素における一般的な誤りをチェックする：短い説明の欠如、ファイルとクラスの可視性の不一致など。
ヘッダーの一貫した使用とドキュメントの確認: 例えば、モジュール内で内部ヘッダーとしてドキュメント化されたヘッダーは、そのモジュール外では使用すべきではありません。
モジュールレベルでの循環依存関係の確認
モジュール間の依存関係グラフ、およびモジュールの内部ファイル間の依存関係グラフを生成する

これらのチェックは、「check-source」という単一のターゲットの一部として実行されますが、以下に個別のセクションで説明されています。問題を「stderr」に出力するだけでなく、スクリプトはそれらを「docs/doxygen/check-source.log」に書き込み、後で確認できるようにします。 CIは、すべてのパイプラインの一部としてこれらのチェックを実行し、問題が見つかった場合はCIが失敗します。

正しく機能するため、スクリプトはDoxygenの注釈（:doc:`doxygen`に記述されている）の適切な使用に依存しており、特にファイルレベルのコメントにある可視性とAPIの定義が重要です。

スクリプトからの誤検出を減らすために、以下の抑制メカニズムを使用するのが最も簡単な方法ですが、それ以外の場合は、抑制の数をできるだけ少なくすることが目標です。

これらのスクリプトはPython 2.7を必要とします（他のバージョンも動作する可能性がありますが、テストされていません）。

スクリプトが内部でどのように動作するかを理解するには、「docs/doxygen/」にあるPythonソースファイル内のコメントを参照してください。

詳細¶

現在、「check-source」ターゲットは、いくつかの異なる種類の問題をチェックします。これらの内容は、主にドキュメントに関連し、依存関係も含まれています。特に、`defgroup`でドキュメント化されたモジュール/ディレクトリ内のコードに対する依存関係のチェックは、非常に厳密です。つまり、そのようなモジュール内のすべての未ドキュメント化されたコードは、モジュールの外部インターフェースとして扱われます。その理由は、そのようなコードにはより多くの注意が払われており、モジュールの外部インターフェースを定義し、それをドキュメント化するための努力も行うべきであるからです。

すべてのDoxygenドキュメント（現在、ドキュメントに表示されないメンバーには適用されません）について：
- メンバーにドキュメントがある場合、簡潔な説明を含んでいる必要があります。
- 関数に関するドキュメントは、現在の設定では無視されるため、本文に記載されたものとして扱われます。
- クラスにドキュメントがある場合、そのドキュメントは、クラスがインストールされたヘッダーに存在する場合にのみ公開ドキュメントとして存在する必要があります。
- もし、クラスとその包含ファイルにドキュメントが存在する場合、ファイルドキュメントが存在しない場合は、クラスのドキュメントが表示されるべきではありません。
すべてのファイルについて：
- :: の一貫した使用
```
#include "..." // This should be used for internal (gromacs) headers
```
  および
```
#include <...> // This should be used for system and external headers
```
- 再度ヘッダーをインストールする場合、それらはインストールされていないヘッダーを含んではいけません。ヘッダーは、それぞれのモジュールの CMakeLists.txt ファイル内でインストール用にマークする必要があります。
- すべてのソースファイルには、「gmxpre.h」を最初のヘッダーとして含める必要があります。
- ソース/ヘッダーファイルは、「config.h」、「gromacs/simd/simd.h」、または「gromacs/ewald/pme_simd.h」を必ず含める必要があります。ただし、これは、そのようなファイルで定義されたマクロを使用する場合のみです。
ドキュメント化されたファイルの場合：
- インストールされたヘッダーには、公開ドキュメントが含まれている必要がありますが、その他のファイルには含まれていません。
- ファイルで指定されたAPIレベルは、そのドキュメントが利用可能なレベルよりも高くなるとはなりません。たとえば、公開されているドキュメントに記載されているヘッダーのみを、公開APIの一部として指定する必要があります。
- もし \ingroup module_foo が存在する場合、それはファイルシステム内のファイルの実際の存在するサブディレクトリと一致している必要があります。
- もし、ファイルが存在するサブディレクトリに \defgroup module_foo が定義されている場合、ファイルには \ingroup module_foo を含める必要があります。
- ファイルには、ドキュメントの可視性が低い他のファイルを含めるべきではありません（含まれるファイルがドキュメント化されていない場合、このチェックはスキップされます）。
ドキュメント化されているモジュール（サブディレクトリに \defgroup module_foo が存在する場合）または、明示的に内部またはライブラリAPIの一部としてドキュメント化されているファイルについては、次のようになります。
- これらのファイルは、ドキュメント化されていない（ドキュメント化されたモジュールの場合）場合、またはライブラリまたはパブリックAPIの一部として指定されていない場合は、外部からインポートしないでください。
すべてのモジュールについて：
- モジュール間には、循環的な依存関係は存在してはなりません。

副作用として、XMLからの抽出により、Doxygenはコード内のすべてのコメントを解析します。これにより、ドキュメントには表示されていないコメント内の潜在的な問題（たとえば、無効なDoxygen構文）が明らかになることがあります。XML解析からのメッセージは、ビルドツリー内の docs/doxygen/doxygen-xml.log に保存され、他のDoxygen実行と同様です。

問題を抑制する¶

このスクリプトは、まだ完璧ではありません（未完成の実装、Doxygenのバグ、またはDoxygenのXML出力の不完全さのため）。現在のコードにも、スクリプトが検出する問題が含まれていますが、これらの問題は作者によって修正されていません。スクリプトが引き続き使用できるように、``doxygen/suppressions.txt``には、レポートから除外される問題のリストが含まれています。構文は以下のとおりです:

<file>: <text>

<file> は、メッセージを報告するファイルのパスであり、<text> は報告されたテキストです。どちらもワイルドカード * をサポートします。 <file> が空の場合、マッチは、関連ファイルのないメッセージのみに適用されます。 <file> は、スクリプトが絶対パスを報告しているにもかかわらず、ファイル名の末尾に一致させることで機能します。空行と # で始まる行は無視されます。

問題を抑制するために、問題を報告する行を suppressions.txt にコピーし、行番号（存在する場合）を削除します。問題にファイル名（または疑似ファイル）が関連付けられていない場合は、先頭に : を追加する必要があります。同様の問題を多数カバーするために、行の一部をワイルドカードで置き換えることができます。

依存関係グラフを含める¶

同じセットのPythonスクリプトは、例えばDoxygenがディレクトリ依存関係グラフとして生成するものと比較して、追加の注釈付きの依存関係グラフも生成できます。現在、Doxygenのドキュメントがビルドされる際に、モジュールレベルのグラフが自動的に作成され、ドキュメントに埋め込まれています（公開APIドキュメントには含まれていません）。グラフと凡例は、別のページにあります: モジュール依存関係グラフ

Python スクリプトは、dot (graphviz パッケージに含まれる) を使用してグラフを配置できるように、適切な形式でグラフを生成します。ビルドシステムには、中間的な dot ファイルから PNG ファイルを生成する dep-graphs というターゲットも用意されています。モジュールレベルのグラフに加えて、各モジュール内のインクルード依存関係を示す、ファイルレベルのグラフも生成されます。ファイルレベルのグラフは、PNG ファイルとしてのみ表示できます。以下に記号の説明を添えて表示します。現在、これらのグラフは主に視覚的な要素として使用されていますが、問題のある依存関係を分析し、アーキテクチャを改善するために使用することもできます。

中間ファイルである .dot ファイルと、最終的な PNG ファイルは、ビルドツリー内の docs/doxygen/depgraphs/ ディレクトリに配置されます。

ファイル: graphs¶

グラフは、module_name-deps.dot.png に書き込まれます。

ノードの色:

薄い青: 公開API (インストール済み) ヘッダー
濃い青: ライブラリ API ヘッダー
灰色: ソースファイル
薄緑: テストファイル
白: その他のファイル

各エッジは、インクルード依存関係を示します。現在、追加の情報は含まれていません。