appledoc導入の際のメモ

インストール

githubからcloneしてXcodeでビルドしてもいいけど、アンインストールなどを考えると、Homebrewを使ったほうが簡単。

$ brew isntall appledoc

なお、ビルドする場合は、https://github.com/tomaz/appledoc からclone後、

$ sudo ./install-appledpoc.sh

を実行するのが楽。

使い方

基本的にはコマンドラインから実行

$ appledoc [option] ソースのパス

ただし、毎回引数を指定するのは面倒なのでAppledocSettings.plistファイルに設定を書いた方が楽。
プロジェクt内に、テンプレートとして、以下のようなAppledocSettings.plistが入っているので、必要なところを編集して使う。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>--company-id</key>
  <string>com.gentlebytes</string>
  <key>--ignore</key>
  <array>
    <string>ThirdParty</string>
    <string>Libraries</string>
    <string>Frameworks</string>
    <string>Testing</string>
  </array>
  <key>--logformat</key>
  <integer>1</integer>
  <key>--print-settings</key>
  <true/>
  <key>--project-company</key>
  <string>Gentle Bytes</string>
  <key>--project-name</key>
  <string>appledoc</string>
  <key>--repeat-first-par</key>
  <false/>
  <key>--templates</key>
  <string>./Templates</string>
  <key>--verbose</key>
  <string>3</string>
</dict>
</plist>

基本的に、タグと、その後に続くやタグがコマンドライン上のパラメータに対応している。
例えば、

  <key>--company-id</key>
  <string>com.gentlebytes</string>

は、引数の　--project-name com.gentlebytes に相当する。
AppledocSettings.plistファイルが引数のソースパス内にある場合は、その内容を参照して実行される
つまり、同じフォルダに置いておけば、以下のコマンドで実行される。

$ appledoc .

AppledocSettings.plistのタグ

要素を省略して、必須なものが指定されていない場合は正しく出力されない。例えばinputを省略するなど。

タグ	説明
--company-id	会社のUTI
--ignore	appledocに解析させないファイルやフォルダのリスト。接頭語ではなく接尾語指定。
--logformat	文字通りログのformat。省略してもいい
--print-settings	実行時にオプションの設定値をコンソールに出力
--project-company	会社名
--project-name	プロジェクト名
--repeat-first-par	先頭行を概要とみなして見出しに使うかどうか。falseだと使わない。
--templates	HTMLのテンプレートファイルへのパス
--verbose	ログレベルの指定。省略することが多い。
--input	解析対象のファイルのリスト。ignore同様複数指定可能。
--output	結果出力先のパス。存在しない場合自動で作る
--create-docset	XCodeのHelpファイルを作成するかどうか
--install-docset	作成したXcodeのhelpファイルをシステムにインストールするかどうか
--create-html	HTML形式のドキュメントを生成する。これがtrueでも--create-docsetがtrueだとHTMLができない。
--exit-threshold	appledocの終了コード指定。jenkinsで使う時に、警告を無視するときなどに使う

AppledocSettings.plistのサンプル

ごく普通に、カレント直下のdocフォルダにHTMLのAPIドキュメントを作成する場合のサンプル

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>--project-name</key>
  <string>testApp</string>
  <key>--project-company</key>
  <string>my campany</string>
  <key>--company-id</key>
  <string>jp.co.hoge</string>
  <key>--output</key>
  <string>doc</string>
  <key>--input</key>
  <array>
    <string>testApp/*.m</string>
    <string>testApp/*.h</string>
  </array>
  <key>--repeat-first-par</key>
  <false/>
  <key>--verbose</key>
  <string>3</string>
  <key>--ignore</key>
  <array>
    <string>testAPP2Tests</string>
    <string>Frameworks</string>
    <string>Products</string>
  </array>
  <key>--exit-threshold</key>
  <integer>1</integer>
  <key>--create-html</key>
  <true/>
</dict>
</plist>

どんな記法が使えるの？

http://dev.classmethod.jp/smartphone/iphone/ios-appledoc-1/ が詳しいので、そちらを参照してください。

面白いポイントとしては、

• ///は解析されるけど//は解析されない（ドキュメントに載らない）。
• 関数ヘッダの一行目は、関数の概要としてクラスヘッダとは扱いが異なる(--repeat-first-parオプションの説明も参照)
• 同じ記号(-とか*とか）を３つ繋げるとコメント内のセパレータとして扱われる

などがあります。