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
【Python入門】使い方とサンプル集
Pythonとは、統計処理や機械学習、ディープラーニングといった数値計算分野を中心に幅広い用途で利用されている人気なプログラミング言語です。主な特徴として「効率のよい、短くて読みやすいコードを書きやすい」、「ライブラリが豊富なのでサクッと...
algorithm.joho.info
コメント