👩🏼‍🏫 🈲 🔉 Doxygenでコードを効率的に文書化する 😓 🖖 🅾️

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

これは、言及されたサイクルの最初の主要な記事であり、開発者の声明に基づいて、実際にC ++で書かれたソフトウェアを文書化するための標準になり、さらに少ないDoxygenソース文書システムの紹介です他のいくつかの言語に広く普及しています。

この記事では、最初にシステム自体とその機能に精通し、次にそのインストールと基本的な動作原理を扱い、最後に、さまざまなドキュメントの例、コードの特定の部分をドキュメント化する方法の例の説明で知り合いを終了します。一言で言えば、私たちはあなたが快適になり、この素晴らしいシステムを使い始めることを可能にするすべてのものに精通します。

はじめに

おそらく、私たちはそれぞれ、さまざまなドキュメントジェネレーターの作業の結果に出くわしました。彼らの仕事の一般的な原則は次のとおりです。そのようなジェネレータの入力は、特別にコメントされたソースコードと、時には他のプログラムコンポーネントを受け取り、出力は配布と使用のための既製のドキュメントを作成します。

検討中のDoxygenシステムはこのタスクを実行するだけです。特別な種類のコメントを含むソースコードに基づいて、リンク、クラス図、呼び出しなどを含む美しく便利なドキュメントを生成できます。さまざまな形式：HTML、LaTeX、CHM、RTF、PostScript、PDF、manページ。

システムの全体的な印象を与えるために、Doxygenを使用して作成されたAPIのさまざまなドキュメントの例を以下に示します（最近の例では、このシステムが生成する標準ドキュメントと比べて目立った変更が行われています）。

注意深い読者は、ほとんどの例でD ++ genがC ++で記述されたソフトウェアの文書化に使用されていることに気づいているはずですが、実際、このシステムは他の多くの言語をサポートしています：C、Objective-C、C＃、PHP、Java、Python 、IDL、Fortran、VHDL、Tcl、および部分的にD。

ただし、確立された伝統に従って、例ではC ++を使用しますが、サポートされている別の言語を好む場合は混乱しないはずです。実際には大きな違いに気付かないため、以下のほとんどはあなたの言語にも当てはまります。

ちなみに、Doxygenを使用したプロジェクトのリストは公式Webサイトで入手でき、これらのプロジェクトのほとんどは無料です。したがって、希望する人は、このプロジェクトまたはそのプロジェクトのソースをダウンロードし、そこで開発者がどのようにドキュメントを実行したかを確認できます。

インストールとセットアップ

Doxygenの最新バージョンは、公式Webサイトからダウンロードできます。そのディストリビューションは、ほとんどの一般的なオペレーティングシステムで利用できます。また、パッケージマネージャーを使用することもできます。さらに、快適でフル機能の作業を行うには、 Graphvizをインストールすることをお勧めします。

さらに、Doxygenの操作は非常に簡単です。設定ファイルへのパスを表示してプログラムを起動するだけです。

doxygen <config_file>

しかし、このファイルにはすべての微妙な点があります。実際には、各プロジェクトには独自の設定ファイルがあり、プロジェクトソースへのパス、ドキュメントを作成するパス、およびドキュメントで詳細に説明されている他のさまざまなオプションが記述され、可能な限り構成することができますニーズに合ったプロジェクト文書。

原則として、このファイルを編集し、一般にDoxygenで作業するには、Doxywizardプログラムを使用できます。これはほとんどの場合Doxygenに付属しており、設定ファイルの操作が少し便利になります（左側はDoxywizard、右側はテキストエディターで開くファイルです）：

それでは、設定ファイルの作成を始めましょう。一般に、Doxywizardを使用する場合、自動的に作成されます。それ以外の場合、このファイルを作成するには、 -gスイッチ（生成から）を指定してDoxygenプログラムを実行する必要があります。

 doxygen -g <config_name>

最初のドキュメントを作成するのに便利な主なオプションを考えてみましょう。

タグ付け	予定	デフォルトで
DOXYFILE_ENCODING	この設定ファイルのすべての文字に使用されるエンコーディング	UTF-8
OUTPUT_LANGUAGE	ドキュメントを生成する言語を設定します。	英語
PROJECT_NAME	プロジェクトの名前。単一の単語または一連の単語にすることができます（Doxywizardの外部で編集している場合、一連の単語は二重引用符で囲む必要があります）	私のプロジェクト
PROJECT_NUMBER	このタグは、プロジェクト番号またはそのバージョンを示すために使用できます。	-
PROJECT_BRIEF	プロジェクトの短い1行の説明。各ページの上部に配置され、プロジェクトの目的の一般的な考えを示します。	-
OUTPUT_DIRECTORY	ドキュメントが生成される絶対パスまたは相対パス	現在のディレクトリ
入力	プロジェクトのソースコードを含む、スペースで区切られたファイルやディレクトリのリスト	現在のディレクトリ
再帰的	指定したディレクトリのサブフォルダー内のソースコードをスキャンする必要がある場合に使用します	いや

設定ファイルに必要な変更（たとえば、言語、プロジェクト名など）を行った後、ドキュメントを生成する必要があります。

それを生成するには、Doxywizardを使用します（このためには、ソースコードを取得する作業ディレクトリを指定し、[実行]タブに移動して[実行doxygen]をクリックします）。または、設定ファイルへのパスをパラメーターとして指定してDoxygenプログラムを実行します：

 doxygen <config_file>

Doxygenドキュメントの基本

Doxygenの設定方法と操作方法がわかったので、今度はコード、基本原則、アプローチを文書化する方法を理解します。

Doxygenのコードドキュメンテーションは、ドキュメントブロックを使用して行われます。その配置には2つのアプローチがあります。

クラス、クラスのメンバー、関数、名前空間などの宣言または定義の前後に配置できます。
または、任意の場所（および別のファイル）に配置することもできますが、そのためには、コードのどの要素を参照するかを明示的に示す必要があります。開発者でさえ回避することを推奨しているため、このアプローチは考慮しませんが、興味があれば、ドキュメントで詳細を読むことができます。

構造的には、ドキュメント化ユニットはコメントであり、特別な方法でフォーマットされているため、その外観は使用する言語に依存するのは当然です（詳細については、ドキュメントの対応するセクションを参照してください）。したがって、さらにCライクな言語（C / C ++ / C＃/ Objective-C / PHP / Java）の構文に注目します。

すぐに、一般に、文書化ブロックには2つの主なタイプがあることに注意してください。複数行ブロックと単一行ブロックです。

それらの違いは、単一行のコメントと複数行のコメントの間よりもわずかに強いです。実際、単一行のブロックで書かれたテキストは、文書化された要素の簡単な説明（見出しに似ています）を指し、複数行のブロックで書かれたテキストは詳細な説明を指します。この違いを忘れてはなりません。

複数行ブロック

ブロックは特別な意味でのコメントであると言いました。したがって、そのような「特別な方法」でどのように決定する必要があります。一般に、複数行ブロックを記述する方法はいくつかあり、特定の方法の選択は好みに応じて異なります。

JavaDocスタイル（通常のCコメントを連想させるが、2つのアスタリスクで始まる）：

 /** * ...   ... * ...   ... */

同時に、各行に星を付ける必要はありません。このようなレコードは同等です：

 /** ...   ... ...   ... */

Qtスタイル。最初のアスタリスクの代わりに感嘆符が付けられます：

 /*! * ...   ... * ...   ... */

前述のオプションの中間星も同様です。これらの2つのスタイルに加えて、いくつかのスタイルがありますが、今のところそれらについては詳しく説明しません。

この場合、このようなコメントで書かれたテキストが詳細な説明を指しているという事実に再度注意を払ってください。

\ briefコマンドを使用して、簡単な説明を示すことができます。コマンドの後、段落の終わりまでに示されるテキストは、短い説明と呼ばれ、空の行は詳細な説明と短い説明を区別するために使用されます。

 /*! \brief     .   */

単線ユニット

単一行のブロックを説明するには、多くの設計方法がありますが、そのうちの2つを検討してください。

C ++スタイルの特別なコメントを使用できます。

///

前のコメントと同様のコメントを使用できますが、追加のスラッシュの代わりに感嘆符を挿入します。

//!

この場合、2つのポイントに注意を喚起したいと思います。

1行のドキュメント単位で詳細な説明を指定するには、 \ detailsコマンドを使用できます。

 /// \details

連続するドキュメント化ブロックは1つに結合されます（使用されるスタイルや、複数行または単一行に関係なく）。

たとえば、次の2つの文書化方法では同じ結果が得られます。

 /// \brief   /// \details

 ///  /*!   */

はい、Doxygenはドキュメンテーション方法に関して非常に柔軟性がありますが、乱用しないでください。また、1つのプロジェクトのフレームワーク内では、常に事前に合意された統一スタイルを順守します。

要素の後のドキュメントブロックの配置

前述のすべての例では、文書化された要素が文書化された要素の前にあると想定されていましたが、文書化された要素の後に配置する方が便利な場合があります。これを行うには、以下の例のように、マーカー「<」をブロックに追加します。

 int variable; ///<

ドキュメントの例

それが実際にどのように見えるか見てみましょう。以下は、以前に検討したルールに従って特定のクラスの文書化されたコードです。

 /*! \brief  ,            :  ,  Doxygen   */ class Parent { public: Parent(); ~Parent(); };

その結果、Doxygenはこれらのコメントに基づいて次の美しくデザインされたページを形成します（ここからの切り抜きです）。

これで基本を学んだので、今度はドキュメントの詳細を知る方法を学びます。このためのツールはチームです。

チーム

私たちは何とかDoxygenのいくつかのチームと知り合うことができました（ \簡単な説明と\詳細について話している）が、実際にはさらに多くのチームがあります。完全なリストは、公式ドキュメントに記載されています。

一般に、Doxygenのコマンドはすべて、記号「\」または「@」が付いた英語の単語（両方のエントリは同一）であり、このようなコマンドは200桁ほどあります。そのようないくつかのコマンドの例を挙げましょう。

チーム	価値
\著者	著者を示します
\バージョン	バージョンを示すために使用
\日付	開発日を示すように設計
\バグ	既知のエラーのリスト
\警告	使用上の警告
\著作権	使用されるライセンス
\例	例にソースへのリンクを示すためにコメントに追加されたコマンド（コマンドの後に追加）
\ todo	このコマンドは、行う必要のある変更（TODO）を記述するために使用されます。

一部のコマンドの使用例と結果を以下に示します。

 /*! \brief   \author Norserium \version 1.0 \date  2015  \warning          ,       Parent */ class Son : public Parent { public: Son(); ~Son(); };

さらに、次の表記法を使用して、コマンドの一般的な形式が指定されるときのコマンドの引数を説明します。

指定	価値
<...>	山括弧は、引数が単一の単語であることを示します。
（...）	括弧は、引数がコマンドが配置される行の終わりまでのすべてのテキストであることを示します
{...}	中括弧は、引数が次の段落までのテキスト全体であることを示します。段落は、空白行または区切りコマンドで区切られます。

さらに、独自のチームを作成できることに注意してください。詳細については、ドキュメントの対応するセクションを参照してください。

ソースコードのコア要素の文書化

これで、一般的なファイルからクラス、構造、関数、メソッドに至るまで、ソースコードのさまざまな要素を文書化する特定の機能を検討できます。

ファイルのドキュメント

目的を説明するドキュメントブロックをファイルの先頭に追加することをお勧めします。このブロックがファイルに属していることを示すには、 \ fileコマンドを使用する必要があります（また、パラメーターとして、このブロックが属するファイルへのパスを指定できますが、デフォルトでは、ブロックが追加されるファイルが選択されます。私たちのニーズに対応しています）。

 /*! \file \brief             ,     */ #ifndef CLASSES_H #define CLASSES_H ... #endif // CLASSES_H

関数とメソッドの文書化

関数とメソッドを文書化する場合、ほとんどの場合、入力パラメーター、関数によって返される値、および考えられる例外を指定する必要があります。適切なコマンドを順番に検討してください。

パラメータ

パラメーターを指定するには、関数パラメーターごとに\ paramコマンドを使用する必要があります。コマンド構文は次のとおりです。

 \param [<>] <_> {_}

コマンドのコンポーネントの意味を考慮してください。

パラメーターの名前は、文書化されたコードでこのパラメーターが認識される名前です。
パラメーターの説明は、使用されるパラメーターの簡単なテキスト説明です。
方向は、パラメーターの目的を示すオプションの属性であり、3つの値「[in]」、「[out]」、「[in、out]」を持つことができます。

すぐに例に進んでください。

 /*!           \param[out] dest    \param[in] src    \param[in] n  ,    */ void memcpy(void *dest, const void *src, size_t n);

その結果、関数のこのようなきちんとしたドキュメントを取得します。

戻り値

戻り値を記述するには、 \ returnコマンド（またはその類似の\ return ）を使用します。構文は次のとおりです。

 \return {__}

戻り値の説明を含む例を考えてみましょう（この場合、パラメーターが1つのコマンドを使用して説明され、その結果、説明に一緒に配置されることに注意してください）。

 /*!     \param a,b   \return   ,     */ double sum(const double a, const double b);

次の結果が得られます。

例外

例外を示すには、 \ throwコマンド（またはその同義語： \ throws 、 \ exception ）を使用します。形式は次のとおりです。

 \throw <-> {}

最も簡単な例を以下に示します。

 \throw std::bad_alloc

クラスのドキュメント

クラスの前にドキュメントブロックを追加するだけで、クラスをドキュメント化することもできます。同時に、Doxygenは言語の構文が与えられると大量の情報を自動的に受信するため、クラスをドキュメント化するタスクは大幅に簡素化されます。そのため、ドキュメント化する際に、Doxygenはクラスのメソッドとメンバー、関数へのアクセスレベル、使いやすい関数などを自動的に定義します。

ご使用の言語がアクセスレベルやメソッドの作成などの特定の概念を明示的にサポートしていないが、それらの存在が暗示され、ドキュメントで何らかの方法で強調したい場合は、いくつかのコマンドがあります（たとえば、 \ public 、 \ private 、\ protected、 \ memberof ）、それらについてDoxygenを明示的に示すことができます。

列挙ドキュメント

列挙の文書化は、他の要素の文書化と大差ありません。それらを便利に文書化する方法を示す例を考えてみましょう。

 ///     enum States { Disabled, ///< ,      Undefined, ///< ,     Enabled, ///< ,      }

つまり、状態の説明は、実際には、簡単な説明または詳細な説明の助けを借りて示されます（この場合、それは役割を果たしません）。

結果は次のようになります。

モジュール

ドキュメント内のモジュールの作成には特別な注意を払う必要があります。これは、モジュールをナビゲートする最も便利な方法の1つであり、その構造化のための効果的なツールであるためです。ここでモジュールごとの適切なグループ化の例を見ることができます。

次に、要点を簡単に検討し、例を示しますが、すべての複雑さを理解したい場合は、ドキュメントの対応するセクションに目を向ける必要があります。

モジュール作成

モジュールを宣言するには、 \ defgroupコマンドを使用することをお勧めします。このコマンドはドキュメントブロックで囲む必要があります。

 \defgroup <> ( )

モジュール識別子はラテン語で書かれた一意の単語であり、後でこのモジュールを参照するために使用されます。モジュールのタイトルは、ドキュメントに表示される任意の単語または文（できれば短いもの）です。

モジュールを説明するとき、特定のモジュールの目的を明らかにするための簡潔で詳細な説明を追加することができることに注意してください、例えば：

 /*! \defgroup maze_generation   \brief  ,    .         : Eller's algorithm, randomized Kruskal's algorithm, cellular automaton algorithm, randomized Prim's algorithm. */

モジュール内の文書化された要素の配置

この要素またはその文書化された要素をモジュールに帰属させるには、2つのアプローチがあります。

最初のアプローチは、 \ ingroupコマンドを使用することです。

 \ingroup <> ( )

欠点は、このコマンドをソースコードの各要素のドキュメントブロックに追加する必要があることです。同じモジュール内には非常に多くの要素があるためです。

したがって、別のアプローチが必要であり、2番目のアプローチはグループの開始および終了コマンド@ {および@}を使用することです。 \ defgroup 、 \ addtogroup 、および\ weakgroupコマンドとともに使用されることに注意してください。

使用例を以下に示します。

 /*! \defgroup <> ( ) @{ */ _ /*! @} */

この例の意味は明確である必要があります。モジュールを宣言し、モジュールの最初と最後の文字で囲まれた特定の文書化された要素を追加します。

ただし、モジュールは1回定義する必要があり、この宣言は1つのファイルのみに含まれます。また、1つのモジュールの要素が異なるファイルに分割されることがよくあるため、グループを再定義せずに1つ追加する\ addtogroupコマンドを使用する必要があります別の要素：

 /*! \addtogroup <> [( )] @{ */ _ /*! @} */

モジュール名はオプションです。実際、このコマンドは\ defgroupコマンドの類似物として使用でき、対応するモジュールが定義されていない場合、対応する名前と識別子で作成されます。

最後に、 \ weakgroupコマンドは\ addtogroupコマンドと似ていますが、異なるモジュールへの同じ要素の割り当てに関連する競合がある場合、それと比較して単純に優先順位が低いという違いがあります。

サブモジュールの作成

サブモジュールを作成するには、サブモジュールを定義するときに、他の文書化された要素のように、特定のサブモジュールに属性を割り当てるだけで十分です。

以下に例を示します。

 /*! \defgroup main_module   */ /*! \defgroup second_module   \ingroup main_module */

複数のモジュールを作成する例

以下は、モジュールを作成する詳細な例です。

ファイルgenerate_maze.h

 /*! \defgroup generate_mazes   \ingroup maze \brief  ,    .         : Eller's algorithm, randomized Kruskal's algorithm, cellular automaton algorithm, randomized Prim's algorithm. */ ///@{ /*! \brief        \param width, height         \returns ,     Maze      */ Maze generateEller(int width, int height); /*! \brief         \param width, height         \returns ,     Maze      */ Maze generateKruskal(int width, int height); /*! \brief         \param width, height         \returns ,     Maze      */ Maze generatePrim(int width, int height); /*! \brief        \param width, height         \returns ,     Maze      */ Maze generateCellular(int width, int height); ///@}

Maze.hファイル

 /*! \defgroup maze  \brief  ,              */ ///@{ class Maze { /*   */ }; ///@}

文書化ブロックのタイプが前述の例と比較してわずかに変更されていることに注意してください。しかし、前述したように、これは基本的な役割を果たさず、より近いオプションを選択します。

その結果、次のドキュメントを取得します。

ドキュメントのテキスト形式

ここで、コードの主要な要素を文書化する方法を一般的な用語で理解した後、文書をより視覚的で表現力豊かで完全なものにする方法を検討します。

ドキュメント内のコード

たとえば、ドキュメントの説明の中には、たとえば、機能を説明するためのコードを追加する必要があります。

\ Codeおよび\ endcodeコマンド

これを行う最も簡単で最も普遍的な方法の1つは、次のように適用される\ codeおよび\ endcodeコマンドを使用することです。

 \code [ {<>}] ... \endcode

使用される言語は、ドキュメントブロックが配置されているファイル拡張子に応じて自動的に決定されますが、この動作が期待を満たしていない場合は、拡張子を明示的に指定できます。

使用例を考えてみましょう。

 /*! \brief   \param a,b  ,           ,          .     : \code int gcd(int a, int b) { int r; while (b) { r = a % b; a = b; b = r; } return r; } \endcode */ int gcd(int a, int b);

結果は次のようになります。

コード例

別のファイルでコードを使用する方法の例を示す方が便利な場合があります。これを行うには、これらのファイルを別のディレクトリに配置し、設定でパスを設定する必要があります。

 EXAMPLE_PATH = __

ドキュメントでコード例を使用できるいくつかの方法を検討してください。

\

コマンド例このコマンドは、ドキュメントブロックがサンプルコードを参照していることを示しています。

 \example <_>

ソースコードのテキストが「例」セクションに追加され、例のソースコードで文書化された要素がチェックされ、見つかった場合は例へのリンクが説明に追加されます。

Gcd.hファイル

 /*! \brief   \param a,b  ,           ,          . */ int gcd(int a, int b); /*! \example main.cpp  ,    */

ファイル例/ main.cpp

, EXAMPLE_PATH = examples

 void main() { int result = gcd(52,106); }

\ includeコマンド

文書化された要素の説明にサンプルコードを追加するために、\ includeコマンドが使用されます。一般的な形式は次のとおりです。

 \include <_>

ファイルの内容を完全にコピーし、コードのブロックとしてドキュメントに挿入します（\ codeコマンドで始まり\ endcodeコマンドで終わるブロック内のコードをフォーマットするのに似ています）。

チーム\スニペット

チーム\スニペット前のチームと同様に、それはあなたが全体のファイルを挿入することを可能にし、その具体的な通路。当然のことながら、その形式はわずかに異なります。

 \snippet <_> ( _ )

特定のコードフラグメントを強調表示するには、フラグメント名の先頭と末尾にドキュメントブロックを配置する必要があります。

 /// [ _ ] ... /// [ _ ]

文書化されたオブジェクトコードの自動実装

最後に、Doxygenは、関数、メソッド、クラス、構造などの本体を詳細な説明に自動的に挿入する機能をサポートしています。これを行うには、次のオプションを使用します。

 INLINE_SOURCES = YES

LaTeXを使用した数式

Doxygenを使用すると、ドキュメントでTeXの式を直接使用できます。非常に便利で、結果は非常にまともです。ただし、制限があることに注意してください。現時点では、式はHTMLおよびLaTeXのドキュメントにしか挿入できませんが、通常はこれで十分です。

数式を表示するには、現在2つのアプローチがあります。

MathJaxを使用して数式を表示するには、設定ファイルで適切なオプションを設定する必要があります。

 USE_MATHJAX = YES

適切な画像を生成し、ドキュメントに挿入します。これらはすべて自動的に行われますが、次のツールが必要になります：latex、dvips、gs。デフォルトでは、式はこのように表示されます。

数式をドキュメントに追加する方法

ドキュメントに式を追加するには、3つの方法があります。ドキュメントの例を使用して、それぞれを連続して検討します。

小文字の式を使用します。これは、コマンド「\ f $」で始まりと終わりが囲まれています。以下に例を示します。

    \f$(x_1,y_1)\f$  \f$(x_2,y_2)\f$  \f$\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}\f$.

結果は次のような線になります。

そして

等しい

別の行から始まり、中央に配置されるリモート式の使用。前の式とは異なり、それらはコマンド「\ f [」で始まり、コマンド「\ f]」で終わりに囲まれています。以下に例を示します。

  \f[ |I_2|=\left| \int_{0}^T \psi(t) \left\{ u(a,t)- \int_{\gamma(t)}^a \frac{d\theta}{k(\theta,t)} \int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi \right\} dt \right| \f]

結果は次のような行になります。

コマンド「\ F {}環境」、あり環境これはラテックス中の特定の環境の名前ですが- 。通常のLaTeXドキュメントで指定されているかのように、指定された環境を使用できます。以下に例を示します。
```
  \f{eqnarray*}{ g &=& \frac{Gm_2}{r^2} \\ &=& \frac{(6.673 \times 10^{-11}\,\mbox{m}^3\,\mbox{kg}^{-1}\, \mbox{s}^{-2})(5.9736 \times 10^{24}\,\mbox{kg})}{(6371.01\,\mbox{km})^2} \\ &=& 9.82066032\,\mbox{m/s}^2 \f}
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     
```
その結果、次の結果が得られます（eqnarray *環境は、いくつかの数式を配置するための番号付けされていない環境です）。

ドキュメント内の式の導入例

LaTeX数式を使用したドキュメントの特定の例を考えてみましょう。

 /*! \brief    \f$ n \f$ \param n - ,     \return \f$ n! \f$       \f$ n \f$,   : \f[ n! = \prod_{i = 1}^ni \f] */ int factorial(int n);

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

Markdownについて簡単に

Markdownは軽量のマークアップ言語です（たとえば、こちらのドキュメントやドキュメントの特別なセクションを参照してください）。バージョン1.8.0以降。Doxygenはこれまで限定的なサポートを提供し、ドキュメントを整理する方法の1つとして機能します（たとえば、ドキュメントまたはHTML挿入を処理するコマンドがありますが、これは普遍的ではありません）。

この言語の詳細と原則をここで説明したくありません。したがって、この言語でドキュメントを「装飾」する方法を検討することに限定します。

 /*!     ------------------------------------------             : -   ; -  ; -      ; -  .       : >      .   ,     ,   , ,   .   —    ,       . > — CAR Hoare    . ![ ](image.png) */ int getRandomNumber();