読者です 読者をやめる 読者になる 読者になる

ITの隊長のブログ

ITの隊長のブログです。いや、まだ隊長と呼べるほどには至っていないけど、日々がんばります。CakePHPとPlayFrameworkを使って仕事しています。最近はAngular2をさわりはじめたお(^ω^ = ^ω^)

Objective-C 開発で、Doxygenを使ってみた

Doxygen Objective-C

スポンサードリンク

(・ωゞ)グシグシグシグシ・・・


(・ω・ )ねみぃ


まだ投稿していないデスマの日々の原因はアプリ開発でした。
無知な私が初級から中の下ぐらいになりました。


んで、最近ソースドキュメントがほしいなぁと思ったので、過去、お世話になったことがある「Doxygen」を自分で使うことにしました。
※「Doxygen」自体は知っていて、誰かが生成したソースドキュメントを読んでいましたが、自分でインストールして、生成したことはなかった。


今回はコレのメモ

  • 環境

Mac OS X ver 10.9.4

  • 言語

Objective-C

Doxygenとは?

Doxygen(ドキシジェン)は、C++C言語JavaObjective-CPython、IDL(CORBAおよびマイクロソフト形式)のためのドキュメンテーションジェネレータである。他にも PHPC#D言語ActionScriptでもある程度利用可能。

wiki引用


説明の通り、ソースコードに適当なコメントを書いておいて、それを元にソースドキュメントを生成してくれます。


また、ドキュメントだけじゃなく「Graphviz」と組み合わせることで、ソースの紐付けをグラフィカルに行ってくれます。めっちゃ便利!


Doxygenを使っているサイト参考
MediaWiki


今回は「Doxygen」と「Graphviz」のインストール手順です。

Doxygenをインストール

Macなので、「brew」コマンドを使います。

$ brew install doxygen 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;
}

んで、ドキュメントを生成すると
下記画像のようになります。
f:id:aipacommander:20140827210454p:plain


ちなみに、特殊コマンドを使っていきましょう。
いろいろな書き方が試せます。

Doxygen - 特殊コマンド

まとめ

小さいプロジェクトであれば、ソース読みはそんなにかかりませんが、大きいプロジェクトになると紐付けがイメージしづらいので、こういった生成ツールに任せると仕事が早くなるかも。


あとは、せっかくコメントを足すので、あとから資料にまとめるときに、別途作成するのもだるいのでこういったツールを使っていこうと思います。


ちなみに下記サイトを参考にしました。
やっぱり公式が一番。

参考にしたサイト

Doxygen 公式サイト

Doxygen 設定ファイル オプション一覧


以上(`・ω・)=3
早く帰れるようになるとうれしいなぁ。