Doxygenでチャートとグラフを作成する

この記事は、Doxygenドキュメンテーションシステムに関する一連の記事の一部です。

1. Doxygenでコードを効率的に文書化する
2. Doxygenのドキュメント
3. Doxygenでチャートとグラフを作成する

彼女は、 Doxygenドキュメンテーションシステムに関する一連の記事を完成させます。 今回は、Doxygenでのさまざまな図とグラフの作成について説明します。 その中で、それらの主なタイプ、それらを設定および設計するさまざまな方法を検討し、それらの使用に関する多くの例とヒントを示します。

はじめに

Doxygenでは、ソースコードに基づいて、ソースコードの特定の要素を説明するために設計された十分に多数のさまざまな図やグラフを自動的に構築できます。ドキュメントのセクション。 彼の仕事の結果は、たとえばこことここで見ることができます （最後の例では、簡潔にするために折りたたまれています）。

それを使用して構築できる主なタイプの図とグラフは次のとおりです。

• クラス継承図
• クラス協力図
• クラス階層図
• コールグラフ
• 呼び出し関数グラフ
• 依存関係グラフ（前方および後方）

次に、これらの各タイプを詳細に検討しますが、最初にいくつかの一般的な発言を行い、それらを構築するときに役立つ主な設定について説明します。 一般に、説明される内容の多くは、ドキュメントの対応するセクションに記載されています 。

ダイアグラムとグラフの構築の基礎

デフォルトでは、さまざまな種類の図やグラフを作成するためのDoxygenの機能は非常に制限されています（クラス継承図のみが利用可能です）。そのような図の例を以下に示します。



より高度なチャートやグラフを作成するには、さまざまな種類のグラフを作成するために設計された特別なオープンソースソフトウェアであるGraphvizが必要です。 こちらからダウンロードできます。

インストール後、Doxygen設定ファイルにいくつかの変更を加える必要があります。 これを行うには、次のコマンドを使用します。

チーム	予定
HAVE_DOT	Graphvizを使用してチャートとグラフを生成する必要があることを示します（デフォルトでは無効）
DOT_PATH	実行可能ファイル「dot.exe」へのパスを指定します（デフォルトでは、パスへのパスがパス変数にあると想定されます。原則として、そうです）。

将来便利になる可能性のある追加の設定のうち、次の点に注意してください。

チーム	予定
DOT_GRAPH_MAX_NODES	グラフに表示されるノードの最大数を設定します。 ノードの数が設定値よりも大きくなると、グラフは切り捨てられ、その結果、子ノードが非表示になった親ノードが赤で強調表示されます（ノードの数がルートノードの子の数より少なく設定された場合、まったく表示されません）
MAX_DOT_GRAPH_DEPTH	グラフの最大深さを設定します（深さは、グラフの最も遠いノードからルートノードまでの面の数に等しくなります）。 繰り返しますが、グラフの深さがこの値を超えると、グラフが切り捨てられ、その結果、子ノードが非表示になった親ノードが赤で強調表示されます。
DOT_IMAGE_FORMAT	チャートとグラフを作成する形式を指定します（「png」、「jpg」、「svg」、「gif」がサポートされます）
DOT_FONTNAME	グラフおよびチャートにテキストを表示するために使用するヘッドセットを設定します。
DOT_FONTSIZE	グラフおよびチャートのテキストのサイズ（文字の高さ、ポイントで測定）を示します。
DOT_FONTPATH	フォントファイルのあるフォルダーへのパスを指定します
HTML_DYNAMIC_SECTIONS	このオプションが設定されている場合、DoxygenはHTMLドキュメントの特定の要素（列など）を折りたたみます。これらの要素は後で表示できます

それで、基本設定を理解したので、チャートとグラフの基本タイプに直接進む準備ができました。

クラス継承図

クラス継承図（クラスグラフ）は、クラス間の継承関係（「上」と「下」の両方）をグラフィカルに表示するように設計されています。

文書化されたすべてのクラスに対してこのような図を生成するには（たとえば、設定ファイルでEXTRACT_ALLオプションが設定されている場合、すべてのクラスが文書化されたクラスに属します）、設定ファイルで次のオプションを設定する必要があります：

CLASS_GRAPH = YES 

以下は、テストケース（Doxygenによって作成された凡例から取られたもの）のようなダイアグラムを作成する例で、クラス間のさまざまなタイプの関係を示しています。



次に、これらまたは他の規則の意味を検討します。

	ルートノード
	文書化されたクラスに対応する通常のノード
	文書化されていないクラスに対応するノード
	子ノードが非表示になっている親ノード（たとえば、グラフ内のノード数またはその深さの制限のため）

	オープン継承を示します
	安全な継承を示します
	閉じた継承を示します
	クラスが特定のテンプレートクラスの特殊化であることを示します。一方、矢印の隣の署名は、特殊化中に指定されたテンプレートパラメーターを示します。

次のオプションに注意する必要があります。

オプション	価値	デフォルトで
HIDE_UNDOC_RELATIONS	文書化されていない場合、またはクラスではない場合、あるクラスとの接続を非表示にする必要があるかどうかを示します。	はい
TEMPLATE_RELATIONS	あるクラスが別のクラスの特殊化であることを示す関係を表示するかどうかを設定します	いや

クラス協力図

クラスコラボレーション図は、クラス間の継承関係（「上位」のみ、つまり親クラスのみが表示される）と、それらの間の相互作用（この場合、属性に含まれる1つのクラスを意味します）のグラフィカル表示を目的としています別のクラスのオブジェクト。

クラス継承図を有効にするには、COLLABORATION_GRAPHコマンドを設定する必要があります。

 COLLABORATION_GRAPH = YES 

以下は、以前に検討された同じ例のクラス協力の図です。


この場合、クラス継承図との違いは、継承されたクラスと使用されたクラスの関係がここに表示されることだけです。これは、最初のクラスが2番目のクラスのインスタンスである属性を持つことで表されます。 この関係の指定は次のとおりです。

1つのクラスに別のクラスのインスタンスである属性が含まれ、矢印の隣の署名が対応する属性の名前を示すことを示します

クラス継承図の設定について前に述べた他のすべては、ここでも有効です。

クラス階層図

クラス階層図は、多くの異なるクラス間の継承関係を示すことのみを目的としています。 実際、これはデフォルトで生成されるクラス階層のテキスト記述のグラフィカルな表現です。

コールグラフ

このタイプのグラフの説明に進む前に、以下に述べるすべてが関数とクラスメソッドに当てはまることに同意しますが、簡潔にするために「関数」という言葉を使用します。 そのため、コールグラフは、ドキュメント化された関数の本体内およびネストされたすべての関数内で呼び出される関数を示します（深さは、設定ファイルでグラフの最大深さを設定することで調整できます）。

関数呼び出しのグラフを作成するには、2つのアプローチを使用できます。すべての関数の呼び出しのグラフを作成するオプションを設定する方法と、関数の説明に追加される特別なコマンドを使用する方法です（特定の関数またはプロジェクトは非常に大規模です）。

最初のアプローチでは、次のオプションを設定する必要があります。

 CALL_GRAPH = YES 

2番目のアプローチでは、次のコマンドが使用されます。

 \callgraph 

呼び出しグラフの例を以下に示します。 以下の画像の式は例として示しています（ 組み合わせ関数は組み合わせの数を計算し、スターリング式を使用して階乗を計算します）。

呼び出し関数グラフ

呼び出し元グラフ。ドキュメント関数が呼び出される結果としてさまざまな関数の呼び出しのチェーンを示します（このようなチェーンの深さは、設定ファイルでグラフの最大深さを設定することで調整できます）。

繰り返しますが、このようなグラフを作成するには2つの方法があります。 最初の方法は、設定ファイルに対応するオプションをインストールすることです：

 CALLER_GRAPH = YES 

2番目の方法は、特別なコマンドを使用することです。

 \callergraph 

呼び出し関数のグラフの簡単な例を以下に示します。


それを簡単に説明しましょう：スターリング公式を使用して階乗を計算するには、累乗（ pow ）の関数が使用され、この関数は指数関数の計算にも使用され、指数関数の計算は双曲線関数の値の計算に使用できます。

依存関係グラフ

依存関係グラフは呼び出しグラフにイデオロギー的に近いですが、呼び出しを示しているのではなく、異なるソースコードファイル間の依存関係を示しています。

直接依存グラフ

直接的な依存関係グラフ（グラフを含む）は、文書化されたファイルまでの依存関係のチェーンを示しています。 どのファイルがドキュメントファイルに接続され、次にどのファイルがそれらのファイルに接続されたかなど

このようなグラフを作成するには、設定ファイルで次のオプションを設定する必要があります。

 INCLUDE_GRAPH = YES 

以下に例を示します。

逆依存関係グラフ

（グラフに含まれる）逆依存関係グラフは、ドキュメントファイルに対する依存関係のチェーンを示しています。 ドキュメント化されたファイルを含むファイル、これらのファイルを含むファイルなど。

このようなグラフを作成するには、設定ファイルで次のオプションを設定する必要があります。

 INCLUDED_BY_GRAPH = YES 

以下に例を示します。

ディレクトリ数

ディレクトリグラフは、問題のディレクトリをグラフィカルに表現したものです。 このようなグラフを作成するには、次のオプションを使用します。

 DIRECTORY_GRAPH = YES 

グラフ要素の1つに赤い線が付いていることに注意してください。これは、このディレクトリに他のディレクトリが埋め込まれていることを意味します。

UMLおよびDoxygen

Doxygenでは、「統一モデリング言語に似たスタイルで」チャートを作成できます。 開発者は、この点に関して非常に正確に表現されています。この機能は、コードに基づいて正確で有能なUMLスキームが構築されることを意味しないため、他のツールをこのタスクに使用する必要があり、UMLが主に表現されるため、多くの場合失敗します特定の実装に非常に近い場合もありますが、アイデア。

したがって、UMLスタイルで図を作成するには、次のオプションを設定する必要があります。

 UML_LOOK = YES 

以前に使用した例に戻りましょう。open、closed、protectedの属性とメソッドを追加するだけです。


残念ながら、図に含める特定のクラスを指定できないという理由だけで、Doxygenは多くの複雑な概念を反映できないことがよくあります。 そのため、たとえば、適用された設計パターンまたは他のソリューションを説明する必要がある場合、別のエディターで回路を作成して単純にインポートする方が簡単で効率的です。 幸いなことに、非常に一般的な特殊なPlantUMLエディターの1つに対して、Doxygenには組み込みのサポートがあります（使用するには、オプションへのパスを指定する必要があります）。

まず、コンピューターにJavaがインストールされ、正しく構成されていることを確認してから、適切なオプションを使用してjarファイルへの正しいパスを指定する必要があります。

 PLANTUML_JAR_PATH = __jar_ 

その後、PlantUMLダイアグラムを挿入するには、対応する\ startumlおよび\ endumlコマンドを使用する必要があります 。

 \startuml [{file}] ["caption"] [<sizeindication>=<size>] ... \enduml 

この場合のパラメーターはすべてオプションです。 fileパラメーターは、生成されたファイルの名前を指定します;指定されない場合、自動的に選択されます; captionパラメーターは、署名をスキームに設定します。 最後のパラメータは、回線のサイズを示すために使用されます。

次に、例に直接進みましょう（「レイアウト」デザインテンプレートの図を以下に示します）。

 /*! \file  (. Composite pattern) —   ,            .            .        UML: \startuml interface Component { +doThis() } class Composite { -elements +addElement() +doThis() } class Leaf { +doThis() } Component <|-- Leaf Component<|-- Composite Composite o-- Component \enduml */ 

結果は以下のとおりです。

おわりに

最後に、スキームは好みのエディターで作成したり、他のジェネレーターを使用して作成したり、結果をDoxygenにインポートできることに注意してください。 一般に、それはすべて、要件と直面するタスクに依存します。 場合によっては、Doxygenが提供する機会で十分であり、この記事があなたにとって楽しい発見になることを願っています。 時には十分ではない場合があり、他のツールや他のソリューションの使用が必要になります。

ご清聴ありがとうございました！