saLibrary

趣味プログラムの記録

ドキュメント生成

doxygenでドキュメントを生成する所まで。

相変わらず外堀を埋めます。
doxygenによるドキュメント生成の準備を行います。

正直、自分しか使わない個人用ライブラリなので丁寧なドキュメントを残すという意図はありません。
ただ、気軽にDoxygenでドキュメント生成できる環境を作っておいたら、
自分のコメントがどうドキュメント化されるのかを意識しながらコーディングするかも。
という希望的観測の元、やってみようと思い立った次第です。

ではさっそくdoxygenをインストール。
コマンドプロンプトでdoxygenと打つと実行可能な状態にしました。

以前、ソースコードをutf8変換するツールを置いた階層にdoxygenディレクトリを作成。
ここに関連するものを配置します。
f:id:sacky003:20170506232137p:plain:w300

そのディレクトリで"doxygen -g"コマンドを実行して設定ファイルを生成。
f:id:sacky003:20170506232448p:plain:w300
DoxyFileというファイルが生成されました。

調子に乗ってCUIで実行しましたが、CUI苦手なゆとりプログラマなのでここからはGUIのDoxywizardで編集いたします。

Doxywizardで先ほど生成されたDoxyFileを開き、
プロジェクト名、出力される言語、ソースの入力ディレクトリ、出力ディレクトリ等を設定。

大体デフォルト値と異なるのは以下のパラメーターでしょうか。

PROJECT_NAME           = saLibrary
OUTPUT_LANGUAGE        = Japanese
INPUT                  = ../../sources
OUTPUT_DIRECTORY       = _doxygen
STRIP_CODE_COMMENTS    = NO
JAVADOC_AUTOBRIEF      = YES

入力元も出力先もこのdoxygenディレクトリからの相対パスで指定。
出力先は_doxygenとしました。(_から始まる名前はgitで無視しています)

Doxygenの設定についてはまだ詳しくないのでこれからも色々と弄ってみます。
大抵の事はここをみればいいかと思います。
http://www.doxygen.jp/config.html
http://www.doxygen.jp/faq.html

doxygenを実行するbatも準備。

@rem ========================================================================
@rem  Doxygenによるドキュメント生成bat
@rem ========================================================================
@echo off
:: 出力先を削除.
set OUTPUT_DIR=_doxygen
if exist "%OUTPUT_DIR%" ( 
  rd /s /q %OUTPUT_DIR% || goto :Error
)
:: 出力先を生成.
mkdir %OUTPUT_DIR% || goto :Error
::doxygenを実行.
call doxygen || goto :Error
echo --- done.
pause
exit /b 0

:Error
Color c
echo --- Error!
pause
exit /b 1

DoxyFileに設定された出力先がない場合はエラーになるので、batでディレクトリを生成しておきます。
生成済みの場合は一旦削除してきれいにします。
f:id:sacky003:20170507001514p:plain:w300

"-g"コマンドでDoxyFileを新規作成しましたが
新規作成されたDoxyFileは全パラメーターがデフォルト値で設定され、さらにパラメーター一つ一つにコメントが丁寧についていて、
後でbatなどでパラメーターを動的に弄りたいという時にパースが面倒だなと感じました。
結局書式は

Key = Value

のようにiniファイルみたいな感じなので、DoxyFileもbatで生成するようにしておけば楽かもしれませんね。

さて、Doxygenで気軽にドキュメントを確認できるようになった所で果たしてちゃんとコメントを頑張るだろうか…。
うーん怪しい。

今回はここまで。