【Python】Doxygenでドキュメンテーションコメントを書いてドキュメント化

DoxygenでPythonにドキュメンテーションコメントを書いて、効率的にドキュメント化について紹介します。

【1】Doxygenとは?概要とメリット

Doxygen(http://www.doxygen.jp/) とは、専用の記法でコメントを書くことで、自動でドキュメントを作成することができ、GNU General Public Licenseで配布されています。
自作ライブラリを公開している場合は、とても便利です。

–	メリット
1	多くのファイル形式（HTML、LATEX、Wordなど）でドキュメントを出力できる。
2	多くの言語に対応している（C++，C，Java，Objective-C，Python，IDL (Corba,Microsoft風)，Fortran，VHDL，PHP，C#など）。Pythonには専用のPydocがあるが、Doxygenの記法ならマルチで使用できる。
2	ソースコードを解析するので一貫性が保たれる。
3	内包・依存図，継承図，およびコラボレーション図により視覚化することができる。
4	昔からあり、ユーザーも比較的多いため、今後も継続的に利用できる可能性が高い。

【2】Doxygenのインストールと環境構築

● 下記コマンドでインストールします。

【Linuxの場合】

$ sudo apt-get install graphviz
$ sudo apt-get install doxygen

【Macの場合】

$ brew install doxygen
$ brew install graphviz

● 今回は下記のようなプロジェクト（mylib）の場合、その直下にドキュメントを作成するためのディレクトリ（例：docフォルダ）を作成します。

mylib
 + CMakeLists.txt
 + src
 |  + sample.cpp
 |  +   ...
 + include
 |  + sample.h
 |  +   ...
 + doc   <追加

● docディレクトリに移動し、doxygenの設定ファイルを作成します。

$ mkdir doc
$ cd doc
$ doxygen -g

● Doxyfileを開き、設定を変更します。

場所	パラメータ	説明
035行	PROJECT_NAME = "mylib"	プロジェクト名
095行	OUTPUT_LANGUAGE = Japanese
774行	INPUT = ../	doxygenに読み込ませるディレクトリを指定（例の場合はmylib）
805行	RECURSIVE = YES	サブディレクトリを管理対象に含めるかどうか（ライブラリなら普通含めるのでYES）

● Doxyfileのあるディレクトリで下記コマンドを実行するとドキュメントが作成されます。

$ doxygen

【3】使用例とテンプレート

個人的に最低限これくらいの項目を書いておけばいいんじゃないかなと思うものを載せてみた
@exampleや@code~@endcodeを用いて使用例を載せるとより良いドキュメントになると思う

# プロジェクト名。Doxygenドキュメントのタイトルなどに使われます。
-PROJECT_NAME           = "My Project"
+PROJECT_NAME           = "任意のプロジェクト名"
# 言語を選択します。（が、あんまり影響はないかも。）
-OUTPUT_LANGUAGE        = English
+OUTPUT_LANGUAGE        = Japanese
# FULL_PATH_NAMES がYESの場合、ファイル名がフルパスで出力され、けっこうわずらわしいです。
-FULL_PATH_NAMES        = YES
+FULL_PATH_NAMES        = NO
# とりあえず全部出す
-EXTRACT_ALL            = NO
+EXTRACT_ALL            = YES
# とりあえず全部出す
-EXTRACT_PRIVATE        = NO
+EXTRACT_PRIVATE        = YES
# とりあえず全部出す
-EXTRACT_STATIC         = NO
+EXTRACT_STATIC         = YES
# とりあえず全部出す
-EXTRACT_ANON_NSPACES   = NO
+EXTRACT_ANON_NSPACES   = YES
# ソースツリーのフォルダ構成が深い場合はマスト
-RECURSIVE              = NO
+RECURSIVE              = YES
# 外部パッケージのディレクトリなどはパッケージの数によっては時間がかかりますので、適宜除外します。
-EXCLUDE                =
+EXCLUDE                = ./vendor
# ソースコードをドキュメントに含めます
-SOURCE_BROWSER         = NO
+SOURCE_BROWSER         = YES
# 被呼び出し関数一覧
-REFERENCED_BY_RELATION = NO
+REFERENCED_BY_RELATION = YES
# 呼び出し関数一覧
-REFERENCES_RELATION    = NO
+REFERENCES_RELATION    = YES
# HTMLの出力ディレクトリを指定します。任意のディレクトリ名でかまいません。
-HTML_OUTPUT            = html
+HTML_OUTPUT            = doxygen
# LaTexいらない
-GENERATE_LATEX         = YES
+GENERATE_LATEX         = NO
# 呼び出しグラフ
-CALL_GRAPH             = NO
+CALL_GRAPH             = YES
# 被呼び出しグラフ
-CALLER_GRAPH           = NO
+CALLER_GRAPH           = YES