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>タグと、その後に続く<string>や<true/><false/>タグがコマンドライン上のパラメータに対応している。
例えば、

```
  <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オプションの説明も参照)
* 同じ記号(-とか*とか）を３つ繋げるとコメント内のセパレータとして扱われる

などがあります。