前々から何かコードを書くたびに、ドキュメントとコメントがないのがいけていないと言い続けてきたが、完全されないまま今に至っていた。
しかし、徐々に書いたコードが増えてきて、自分でもよくわからなくなってきたので、しぶしぶドキュメントを作成することを決意した。決意はしたものの、ちまちまと手で書くのはやはり面倒なので、できるだけ自動生成をしてやろうと思い、doxygenを使おうことにした。
ざっとdoxygenのマニュアルを眺めると、どうやらこんな感じで書けばいいらしい。
/// 要約説明
空白行
/// 詳細説明
/// 詳細説明の続き
こんな感じ書いてやると、直後のクラスや関数の説明と解釈してくれるようだ。要は1行で要約を書いて空行を挟んで詳細説明を書けばいいらしい。
ここで少し欲張ってみることにして、もう少しドキュメントをちゃんと読んでみることにした。よく読むと、引数やメンバ変数などにも説明をつけれるようだ。どうも"\param 変数名 説明"を詳細説明の中に入れるといいらしい。さらに、変数の前にも上に書いたスタイルで説明を追加できるようだ。
こんな感じで、dglwindow.hppにはなんとかコメントを追加し終わった。その結果をdoxygenでhtmlとして出力したのがこちら。
次にdoxygenではTeX出力もしてくれるということがわかったので、TeX→PDFに挑戦した。
何も考えずにTeXアウトプットを選択すると、makeするときに失敗する。デフォルトの設定ではlatexコマンドを使用するようなので、platexにして文字コードをUTF-8を使用するようにした。また、PDFLaTeXも日本後では失敗するようなので、こちらも使用しないように変更した。
LATEX_CMD_NAME : platex -kanji=utf8
PDFLATEX : チェックを外す
出力ディレクトリで、次のコマンドを実行するとPDFが作成される。
$ make && dvipdfmx refman
結果はこちら→>refman.pdfをダウンロード
なかなかそれっぽいものができた。
コメント