実行可能ファイル doxygen は、ソースコードを解析し、ドキュメントを生成するメインプログラムです。詳細な使用方法については、Doxygen の使用方法のセクションを参照してください。
オプションで、実行可能ファイル doxywizard を使用できます。これは、Doxygen が使用する設定ファイルを編集したり、グラフィカル環境で Doxygen を実行するためのグラフィカルフロントエンドです。macOS の場合、Doxywizard は Doxygen アプリケーションアイコンをクリックすると起動します。
次の図は、ツール間の関係と情報フローを示しています（複雑に見えますが、それは完全を期しているためです）。
まず、あなたのプログラミング/ハードウェア記述言語が Doxygen によって認識される可能性が高いことを確認してください。これらのプログラミング言語はデフォルトでサポートされています: C, C++, Lex, C#, Objective-C, IDL, Java, PHP, Python, Fortran, D。Doxygen はハードウェア記述言語 VHDL もデフォルトでサポートしています。特定のファイルタイプの拡張子に特定のパーサーを使用するように設定できます。詳細については、Configuration/ExtensionMappings を参照してください。また、完全に異なる言語もプリプロセッサプログラムを使用することでサポートできます。詳細については、ヘルパーページを参照してください。
Doxygen は、すべての設定を決定するために設定ファイルを使用します。各プロジェクトは独自の設定ファイルを持つ必要があります。プロジェクトは単一のソースファイルで構成することも、再帰的にスキャンされるソースツリー全体で構成することもできます。
設定ファイルの作成を簡略化するために、Doxygen はテンプレート設定ファイルを作成できます。これを行うには、コマンドラインから doxygen を -g オプション付きで呼び出します。
doxygen -g <config-file>
ここで、<config-file> は設定ファイルの名前です。ファイル名を省略すると、Doxyfile という名前のファイルが作成されます。<config-file> という名前のファイルがすでに存在する場合、Doxygen は設定テンプレートを生成する前に、そのファイルの名前を <config-file>.bak に変更します。ファイル名として - （つまり、マイナス記号）を使用すると、Doxygen は標準入力 (stdin) から設定ファイルを読み取ろうとします。これはスクリプト作成に役立ちます。
設定ファイルは、（単純な）Makefile の形式に似た形式を持っています。それは、次の形式の多数の割り当て（タグ）で構成されています。
TAGNAME = VALUE または
TAGNAME = VALUE1 VALUE2 ...
生成されたテンプレート設定ファイル内のほとんどのタグの値をデフォルト値のままにすることができます。設定ファイルの詳細については、設定セクションを参照してください。
テキストエディタで設定ファイルを編集したくない場合は、Doxywizard を試してみてください。これは、Doxygen 設定ファイルの作成、読み取り、書き込みを行うことができ、ダイアログから設定オプションを入力できるようにする GUI フロントエンドです。
数個の C および/または C++ ソースファイルとヘッダーファイルで構成される小規模プロジェクトの場合、INPUT タグを空のままにすると、Doxygen は現在のディレクトリでソースを検索します。
ソースディレクトリまたはツリーで構成される大規模プロジェクトがある場合は、ルートディレクトリまたはディレクトリを INPUT タグに割り当て、1 つ以上のファイルパターンを FILE_PATTERNS タグに追加する必要があります（例: *.cpp *.h）。パターンのいずれかに一致するファイルのみが解析されます（パターンが省略されている場合、Doxygen がサポートするファイルタイプに対して一般的なパターンのリストが使用されます）。ソースツリーの再帰的な解析を行うには、RECURSIVE タグを YES に設定する必要があります。解析されるファイルのリストをさらに微調整するために、EXCLUDE および EXCLUDE_PATTERNS タグを使用できます。たとえば、ソースツリーからすべての test ディレクトリを省略するには、次のように使用できます。
EXCLUDE_PATTERNS = */test/*
Doxygen は、ファイルの拡張子を見て、ファイルを解析する方法を決定します。次の表を使用します。
| 拡張子 | 言語 | 拡張子 | 言語 | 拡張子 | 言語 |
|---|---|---|---|---|---|
| .dox | C / C++ | .HH | C / C++ | .py | Python |
| .doc | C / C++ | .hxx | C / C++ | .pyw | Python |
| .c | C / C++ | .hpp | C / C++ | .f | Fortran |
| .cc | C / C++ | .h++ | C / C++ | .for | Fortran |
| .cxx | C / C++ | .mm | C / C++ | .f90 | Fortran |
| .cpp | C / C++ | .txt | C / C++ | .f95 | Fortran |
| .c++ | C / C++ | .idl | IDL | .f03 | Fortran |
| .cppm | C / C++ | .ddl | IDL | .f08 | Fortran |
| .ccm | C / C++ | .odl | IDL | .f18 | Fortran |
| .cxxm | C / C++ | .java | Java | .vhd | VHDL |
| .c++m | C / C++ | .cs | C# | .vhdl | VHDL |
| .ii | C / C++ | .d | D | .ucf | VHDL |
| .ixx | C / C++ | .php | PHP | .qsf | VHDL |
| .ipp | C / C++ | .php4 | PHP | .l | Lex |
| .i++ | C / C++ | .php5 | PHP | .md | Markdown |
| .inl | C / C++ | .inc | PHP | .markdown | Markdown |
| .h | C / C++ | .phtml | PHP | .ice | Slice |
| .H | C / C++ | .m | Objective-C | ||
| .hh | C / C++ | .M | Objective-C |
上記のリストには、FILE_PATTERNS でデフォルトで設定されているよりも多くの項目が含まれている可能性があることに注意してください。
解析されない拡張機能は、FILE_PATTERNS に追加し、適切な EXTENSION_MAPPING を設定することで設定できます。
既存のプロジェクト（つまり、Doxygen が認識しているドキュメントがないプロジェクト）で Doxygen を使い始める場合でも、構造がどのようになっているか、ドキュメント化された結果がどのように見えるかのアイデアを得ることができます。これを行うには、設定ファイル内の EXTRACT_ALL タグを YES に設定する必要があります。すると、Doxygen はソース内のすべてがドキュメント化されていると見なします。その結果、EXTRACT_ALL が YES に設定されている限り、ドキュメント化されていないメンバーに関する警告は生成されないことに注意してください。
既存のソフトウェアを分析するには、（ドキュメント化された）エンティティとそのソースファイル内の定義を相互参照すると便利です。Doxygen は、SOURCE_BROWSER タグを YES に設定すると、そのような相互参照を生成します。また、INLINE_SOURCES を YES に設定することで、ソースをドキュメントに直接含めることもできます（これは、たとえばコードレビューに役立ちます）。
ドキュメントを生成するには、次のように入力します。
doxygen <config-file>
設定に応じて、Doxygen は出力ディレクトリ内に html, rtf, latex, xml, man, および/または docbook ディレクトリを作成します。名前が示すように、これらのディレクトリには、HTML、RTF、
、XML、Unix-Man ページ、および DocBook 形式で生成されたドキュメントが含まれています。
デフォルトの出力ディレクトリは、doxygen が起動されたディレクトリです。出力が書き込まれるルートディレクトリは、OUTPUT_DIRECTORY を使用して変更できます。出力ディレクトリ内の形式固有のディレクトリは、設定ファイルの HTML_OUTPUT, RTF_OUTPUT, LATEX_OUTPUT, XML_OUTPUT, MAN_OUTPUT, および DOCBOOK_OUTPUT タグを使用して選択できます。出力ディレクトリが存在しない場合、doxygen はディレクトリを作成しようとしますが、mkdir -p のようにパス全体を再帰的に作成しようとはしません。
生成された HTML ドキュメントは、HTML ブラウザで html ディレクトリの index.html ファイルを開くことで表示できます。最良の結果を得るには、カスケードスタイルシート（CSS）をサポートするブラウザを使用する必要があります（生成された出力をテストするために、Mozilla Firefox、Google Chrome、Safari、および場合によっては IE8、IE9、Opera を使用しています）。
HTML セクションの機能の一部（GENERATE_TREEVIEW や検索エンジンなど）は、Dynamic HTML と JavaScript が有効になっているブラウザが必要です。
生成された ドキュメントは、最初に コンパイラでコンパイルする必要があります（私は Linux および macOS 用には最新の teTeX ディストリビューション、Windows 用には MikTex を使用しています）。生成されたドキュメントのコンパイルプロセスを簡略化するために、doxygen は latex ディレクトリに Makefile を書き込みます（Windows プラットフォームでは make.bat バッチファイルも生成されます）。
Makefile の内容とターゲットは、USE_PDFLATEX の設定によって異なります。無効になっている場合（NO に設定）、latex ディレクトリで make と入力すると、refman.dvi という名前の dvi ファイルが生成されます。このファイルは、xdvi を使用して表示したり、make ps と入力して PostScript ファイル refman.ps に変換したりできます（これには dvips が必要です）。
1 つの物理ページに 2 ページを配置するには、代わりに make ps_2on1 を使用します。結果として得られる PostScript ファイルは、PostScript プリンターに送信できます。PostScript プリンターがない場合は、ghostscript を使用して PostScript をプリンターが理解できるものに変換してみてください。
ghostscript インタープリターをインストールしている場合は、PDF への変換も可能です。make pdf (または make pdf_2on1) と入力するだけです。
PDF 出力で最良の結果を得るには、PDF_HYPERLINKS および USE_PDFLATEX タグを YES に設定する必要があります。この場合、Makefile には refman.pdf を直接ビルドするためのターゲットのみが含まれます。
Doxygen は RTF 出力を refman.rtf という単一のファイルに結合します。このファイルは、Microsoft Word へのインポートに最適化されています。特定の情報は、いわゆるフィールドを使用してエンコードされます。実際の値を表示するには、（編集 - すべて選択）を選択し、フィールドを切り替える必要があります（右クリックしてドロップダウンメニューからオプションを選択します）。
XML 出力は、Doxygen によって収集された情報の構造化された「ダンプ」で構成されています。各コンパウンド（クラス/名前空間/ファイル/ ...）には独自の XML ファイルがあり、index.xml という名前のインデックスファイルもあります。
combine.xslt という名前の XSLT スクリプトも生成され、すべての XML ファイルを単一のファイルに結合するために使用できます。
Doxygen は、2 つの XML スキーマファイル index.xsd （インデックスファイル用）と compound.xsd （コンパウンドファイル用）も生成します。このスキーマファイルは、可能な要素、その属性、およびそれらの構造化方法を記述します。つまり、XML ファイルの文法を記述し、検証または XSLT スクリプトの制御に使用できます。
addon/doxmlparser ディレクトリには、Doxygen によって生成された XML 出力を段階的に読み取るためのパーサーライブラリがあります（ライブラリのインターフェースについては、addon/doxmlparser/doxmparser/index.py および addon/doxmlparser/doxmlparser/compound.py を参照してください）。
生成された man ページは、man プログラムを使用して表示できます。man ディレクトリが man パスにあることを確認する必要があります（MANPATH 環境変数を参照）。man ページ形式の機能にはいくつかの制限があるため、一部の情報（クラス図、相互参照、数式など）は失われることに注意してください。
Doxygen は、DocBook 形式で出力することもできます。DocBook 出力を処理する方法は、このマニュアルの範囲外です。
ソースコードのドキュメント化はステップ 3 として提示されていますが、新しいプロジェクトでは、もちろんステップ 1 である必要があります。ここでは、すでにコードがあり、Doxygen に API と、場合によっては内部構造、および関連する設計ドキュメントを記述する優れたドキュメントを生成させたいと想定しています。
設定ファイルで EXTRACT_ALL オプションが NO （デフォルト）に設定されている場合、Doxygen はドキュメント化されたエンティティのドキュメントのみを生成します。では、これらをどのようにドキュメント化するのでしょうか？メンバー、クラス、名前空間には、基本的に 2 つのオプションがあります。
メンバー、クラス、または名前空間の宣言または定義の前に特別なドキュメントブロックを配置します。ファイル、クラス、および名前空間メンバーの場合、メンバーの直後にドキュメントを配置することも許可されています。
特別なドキュメントブロックの詳細については、特別なコメントブロックセクションを参照してください。
特別なドキュメントブロックを別の場所（別のファイルまたは別の場所）に配置し、ドキュメントブロックに構造コマンドを記述します。構造コマンドは、ドキュメントブロックをドキュメント化できる特定のエンティティ（メンバー、クラス、名前空間、ファイルなど）にリンクします。
構造コマンドの詳細については、他の場所でのドキュメントセクションを参照してください。
最初のオプションの利点は、エンティティの名前を繰り返す必要がないことです。
ファイルは、ファイルの前にドキュメントブロックを配置する方法がないため、2 番目のオプションを使用してのみドキュメント化できます。もちろん、ファイルメンバー（関数、変数、typedef、define）は明示的な構造コマンドを必要としません。特別なドキュメントブロックを前または後ろに配置するだけで正常に機能します。
特別なドキュメントブロック内のテキストは、HTML および/または 出力ファイルに書き込まれる前に解析されます。
*）が続き、さらにオプションで空白文字が続く場合、すべての空白文字とアスタリスクが削除されます。 出力用に 相当物に変換されます。サポートされているすべての HTML タグの概要については、HTML コマンドセクションを参照してください。