ドキュメントジェネレーターDoxygenの導入

Doxygenはソースコードに一定の書式でコメントを書いておくと、そこからソースコードのドキュメントを自動で生成してくれるソフトです。今回はPythonへの適用の方法を書いていきます。Linux/Debianで使用します。

1.インストール

$apt-get install doxygen doxygen-gui graphviz

2.GUIで設定

$doxywizard
でGUIでの設定画面が開きます。まずStep1というところにソースファイルのあるディレクトリを指定します。
設定すべき項目は「Wizard」の「Mode」ではOptimize for Java or C# （for Pythonという物はなく、これを選ぶのが良いらしい）

「Output」ではHTMLのみにチェックを付けて、ラジオボタンはwith navigation panelにします。

あとは「Run」のタブでRun Doxygenを選ぶだけでHTMLというディレクトリが生成されてそのならのIndex.htmlを開くと生成されたドキュメントが読めます。

メニューバーの「Setting」からUse current setting for startupを選ぶと現在の設定がデフォルトに登録されます。

3.書き方

以下のようなファイルを変換すると

## @package pyexample
#  Documentation for this module.

## Documentation for a function.
def func():
    pass

## Documentation for a class.
class PyClass:

    ## The constructor.
    def __init__(self):
        self._memVar = 0;

    ## Documentation for a method.
    #  @param self The object pointer.
    #  @return 0 fixed
    def PyMethod(self):
        return 0

    ## A class variable.
    classVar = 0;
 

下記のようになります（全部写っていないのですが雰囲気だけ）。

pythonのは#から先がコメントになります。doxygenで使うテキストはコメント部分に書きます。

ただし最初の行だけは##から始める必要があります。

例えばクラスの説明をしたい場合にはクラスの宣言の直前に書くとその部分がクラスの説明とみなされます。また@から始まる特別なコマンドがあります。DoxygenのWebサイトに一覧がありますが主なものを乗せておきます。

• @package
  パッケージの情報を記述します。
• @date
  日付の情報を記述します
• @version
  バージョン情報を記述します。
• @code～@endcode
  コードを記述します。この領域では改行の省略などがされなく、書いたものがそのまま表示されます。@codeではじめて、必ず@endcodeで閉じる必要があります。
• @param
  関数の説明文でパラメーターの説明を記述します。@param [変数名] [説明]と書きます。
• @return
  関数の説明文で返り値の説明を記述します。