(・ωゞ)グシグシグシグシ・・・
(・ω・ )ねみぃ
まだ投稿していないデスマの日々の原因はアプリ開発でした。
無知な私が初級から中の下ぐらいになりました。
んで、最近ソースドキュメントがほしいなぁと思ったので、過去、お世話になったことがある「Doxygen」を自分で使うことにしました。
※「Doxygen」自体は知っていて、誰かが生成したソースドキュメントを読んでいましたが、自分でインストールして、生成したことはなかった。
今回はコレのメモ
- 環境
Mac OS X ver 10.9.4
- 言語
Doxygenとは?
Doxygen(ドキシジェン)は、C++、C言語、Java、Objective-C、Python、IDL(CORBAおよびマイクロソフト形式)のためのドキュメンテーションジェネレータである。他にも PHP、C#、D言語、ActionScriptでもある程度利用可能。
wiki引用
説明の通り、ソースコードに適当なコメントを書いておいて、それを元にソースドキュメントを生成してくれます。
また、ドキュメントだけじゃなく「Graphviz」と組み合わせることで、ソースの紐付けをグラフィカルに行ってくれます。めっちゃ便利!
設定ファイルを生成
適当にディレクトリを作って移動します。移動したところが、ドキュメントが生成される場所になります。
それではコマンドを使って、デフォルトの設定ファイルを生成します。
$ doxygen -g Configuration file `Doxyfile' created. Now edit the configuration file and enter doxygen Doxyfile to generate the documentation for your project
こんな感じの結果が出力されたのち
$ ls Doxyfile $ mv Doxyfile doxygen.conf
「Doxyfile」というファイルが出来上がりますので、名前をちっとわかりやすくします。
設定ファイルの変更
デフォルトのままじゃ使えないので、下記のようにします。
注意点として、プログラミング言語のC系に言えたことですが、Doxygenの設計思想としては、ヘッダーファイルに載せている「公開してもよい情報」のドキュメントを生成するので、デフォでは実装ファイルとか、内部メソッドはドキュメントとして生成されません。
※今回これにハマった(;ω;)
なので、ドキュメントの用途によって設定は細かくしていくようにいきましょう。ちなみに柔軟な設定ができると喜ばれていますが、柔軟性高すぎてドキュメントの量はめっちゃ多いです。(;`・ω・)
$ wc -l doxygen.conf 2310 doxygen.conf
私は下記のように設定しました。
$ vim doxygen.conf ###ここからはファイルの中身#### # 解析したいプロジェクトの名前 ドキュメントのタイトルになります. PROJECT_NAME = "Your Project Name" # 再帰的にソースコードのファイルを探索する RECURSIVE = YES # LaTeX で出力しない GENERATE_LATEX = NO # Graphviz で出力するための DOT ファイルを作る HAVE_DOT = YES # DOT ファイルの生成をマルチスレッドで行う. # 実行環境には注意.クッソ重くなります. DOT_NUM_THREADS = 4 # コールグラフ (呼び出す側) を作る CALL_GRAPH = YES # コールグラフ (呼び出される側) を作る CALLER_GRAPH = YES # 読み込むコードの拡張子を選定します。通常はデフォルトでも構いません。 # 今回はObjective-Cだったので *.mと*.hになります。 FILE_PATTERNS = *.m *.h # 生成するプロジェクトのパス(環境に合わせて修正ください) INPUT = "/usr/local/testProject/" # ドキュメントファイルを生成するディレクトリを選定 OUTPUT_DIRECTORY = "/usr/local/testProject/doc/" # ドキュメントにソースコードのhtmlファイルを作成します # いちいちソースコード表示のために、エディタを起動しなくともOKです SOURCE_BROWSER = YES # ドキュメントの詳細で関連のソースコードを表示します。 # メソッド単位に作成されるのでドキュメントは多くなりますが # いちいちページ遷移しなくともいいので、コードレビューとかで便利かも INLINE_SOURCES = YES # JavaDoc的な書き方のコメントをドキュメントにすることができます。 # JavaDocで書きたい場合はこれをYESにしましょう。 JAVADOC_AUTOBRIEF = YES # よくわからないけど、ドキュメントなくても一応ドキュメント生成しますよ? # 的なものらしい。。。(´・ω・)? EXTRACT_ALL = YES # Privateなメンバーをドキュメントに出力します. EXTRACT_PRIVATE = YES # staticメンバーをドキュメントに出力 EXTRACT_STATIC = YES # ローカルで定義されたクラスをドキュメントに出力 # 時と場合に注意ですね。 EXTRACT_LOCAL_CLASSES = YES # ローカルで定義されたメソッドをドキュメントに出力 # 上記の「EXTRACT_LOCAL_CLASSES」と同様に使いドコロに注意です。 EXTRACT_LOCAL_METHODS = YES # 画面上部のタブをつけない DISABLE_INDEX = YES # 検索用テキストボックスをつけない SEARCHENGINE = NO # 画面左側のTreeViewをつけない GENERATE_TREEVIEW = NO ###########################
・・・(・ω・ )
長い!(°Д° )ゴラァ!
ドキュメント生成
ここまでお疲れ様です。それではドキュメントファイルを生成します.
$ doxygen doxygen.conf
実行後ですが、ソースコードの量にもよりますが1分もかからないと思います。
※ソースが200ぐらいあれば、5〜10分ぐらい
finished...
これがでれば終了です。
あとは「OUTPUT_DIRECTORY」に設定した場所にファイルができあがっていれば完了となります。
コメントの書き方
設定で「JAVADOC_AUTOBRIEF」を有効にしている場合で下記のようなコメントとコードを追加します。
/** * テスト用のメソッドです * * @param size * サイズの引数を受け取ります(`・ω・)b * * @date * 2014/08/27 12:00 * * @author * Commander Aipa */ - (void)hogeHogeFugaFuga:(CGRect)size { UITableView *hogeHoge = [[UITableView alloc] initWithFrame:size style:UITableViewStylePlain]; hogeHoge.delegate = self; hogeHoge.dataSource = self; }
んで、ドキュメントを生成すると
下記画像のようになります。
ちなみに、特殊コマンドを使っていきましょう。
いろいろな書き方が試せます。