このブログは、旧・はてなダイアリー「檜山正幸のキマイラ飼育記 メモ編」（http://d.hatena.ne.jp/m-hiyama-memo/）のデータを移行・保存したものであり、今後（2019年1月以降）更新の予定はありません。

今後の更新は、新しいブログ http://m-hiyama-memo.hatenablog.com/ で行います。

Doxygenの使い方

その他ソフトウェア

Doxygenはインストールも簡単だし、使い方も簡単で割とスルスルと使えてしまう、よく出来たソフトウェアだなー。だけど、それでも忘れそうだからメモしておく。

プロジェクトディレクトリのルート（トップレベル）にDoxyfileと置く。doxygenの動作は、Doxyfileで完全に制御される。



$ doxygen --version

1.8.11
$ doxygen --help

Doxygen version 1.8.11

Copyright Dimitri van Heesch 1997-2015
You can use doxygen in a number of ways:
1) Use doxygen to generate a template configuration file:

    C:\Installed\doxygen\bin\doxygen.exe [-s] -g [configName]
    If - is used for configName doxygen will write to standard output.
2) Use doxygen to update an old configuration file:

    C:\Installed\doxygen\bin\doxygen.exe [-s] -u [configName]
3) Use doxygen to generate documentation using an existing configuration file:

    C:\Installed\doxygen\bin\doxygen.exe [configName]
    If - is used for configName doxygen will read from standard input.
4) Use doxygen to generate a template file controlling the layout of the

   generated documentation:

    C:\Installed\doxygen\bin\doxygen.exe -l [layoutFileName.xml]
5) Use doxygen to generate a template style sheet file for RTF, HTML or Latex.

    RTF:        C:\Installed\doxygen\bin\doxygen.exe -w rtf styleSheetFile

    HTML:       C:\Installed\doxygen\bin\doxygen.exe -w html headerFile footerFi

le styleSheetFile [configFile]

    LaTeX:      C:\Installed\doxygen\bin\doxygen.exe -w latex headerFile footerF

ile styleSheetFile [configFile]
6) Use doxygen to generate a rtf extensions file

    RTF:   C:\Installed\doxygen\bin\doxygen.exe -e rtf extensionsFile
If -s is specified the comments of the configuration items in the config file wi

ll be omitted.

If configName is omitted `Doxyfile' will be used as a default.
-v print version string
$

指示に従い、doxygen -g でDoxyfileを作る。別な名前にするのはやめたほうがいいだろう。



$ cd project-dir
$ doxygen -g



Configuration file `Doxyfile' created.
Now edit the configuration file and enter
  doxygen Doxyfile
to generate the documentation for your project



$

このあと、doxygen とだけ打つと、それでドキュメントは生成される。Doxyfileをカスタマイズしたが、何をどう書き換えたっけな？

  1. プロジェクト名（タイトルになる）を設定した。PROJECT_NAME = "ホゲ ホゲ"。値に空白が含まないならクォートは要らない。
  2. 今回は入力がShift_JISである必要があるので、INPUT_ENCODING = CP932 とした。デフォルトがUTF-8だから、普通は直す必要がない。
  3. 入力ファイルのglobパターンを FILE_PATTERNS = *.cpp *.h *.markdown にした。.mdじゃなくて.markdownにしたのには理由がある（後述）。
  4. 生成されるHTMLの表示を GENERATE_TREEVIEW = YES とした。これは好みが別れるところで、ツリービューはうるさい感じにはなる。
  5. LaTeX出力は不要なので、GENERATE_LATEX = NOとした。
  6. いくつかのファイルをEXCLUDE = hoge.h fuga.cpp で除外した。EXCLUDE_PATTERNS も使える。
  7. EXTRACT_ALL = YES とした。こうすると、コメントなしの構成要素もドキュメントされる。警告が出なくなるので良し悪しだが、最初はこうしたほうがいいように思う。

事情があってソースコードのエンコーディングはShift_JIS、拡張子ごとにエンコーディングを変えるとかは出来ないので、Markdownファイルに多少の細工。.md拡張子で原稿を書いて、MakefileでShift_JISに変える。

%.markdown : %.md
	cat $< | iconv -f UTF-8 -t CP932 > $@

doxygenが読むのは.markdown拡張子のファイル。これで、ソースコードもmarkdown文書ファイルも全てShift_JISで揃う。.markdownファイルは中間一時ファイルの扱い。.mdファイルの先頭のemacs用の<!-- -*- coding: utf-8 -*- -->は消さない！ これを付けておくと、.markdownファイルが文字化けするので、間違って中間ファイルを編集するリスクがなくなる。

.mdをUTF-8のままにしておくのは、pandocなどのツールがUTF-8しか扱えないから。それと、特別な事情がない限りはなるべくUTF-8にしておきたいから。

[追記]

HTMLドキュメントのフロントページに書く内容は、@mainpage（または \mainpage）コマンドを使って書く。どのファイルに書いてもいいが、Readme.doxy.h のようなドキュメント専用のファイルを作ってもいい。

/** @mainpage このプロジェクトについて
 *
 * @section first はじめに
 *
 * ...
 * ...
 */

使えるドキュメント用コマンドはたくさんある。http://www.doxygen.jp/commands.html にリファレンスがある。

[/追記]