2012/06/11

appledocを使ってObjective-CソースをXcode Organizerで表示できるようにする

appledocはObjective-CのAPIドキュメントを作成することができるコマンドラインツールです。 コマンドラインで簡単にApple風のドキュメントを作成できるようなので試してみました。

実行例

つまらない例ですが、こんな感じのソースが…

    /**
     * サンプルクラス
     */
    @interface MySample : NSObject

    /// @name 値の増加

    /** 指定した値だけ value を増加させる。
     *
     * value は正の整数である必要がある。
     * @param  v 増加値
     * @return 増加させる前の value の値
     */
    - (id)addValue:(int)v;

    /// @name 値

    /// なんかの値
    @property (nonatomic,assign) int value;
    @end

Xcode Organizerで次のように表示することができます。

appledocのコンパイル

現在、appledocはバイナリが用意されていませんので、次のような手順でソースを取得して自分でコンパイルする必要があります。

  1. GitHub.appでappledocのソースを取得します。
  2. 取得したソースの中にあるappledoc.xcodeprojでXcodeを起動してコンパイル。
  3. Product Navigator中のProductからappledocを右クリック→Show in Finderします。
  4. Finderのappledocをどこかに置きます。ここではホーム直下(~/appledoc)に置きます。
  5. mkdir ~/.appledoc
  6. mv ~/src/github/appledoc/Templates/* ~/.appledoc

なお、2.以降を手動でやるのが面倒な人向けにinstall-appledoc.shが用意されています。 このスクリプトではデフォルトではappledocを/usr/local/binに、テンプレートを~/.appledocに配置します。

    sudo sh install-appledoc.sh

appledocの利用法

appledocを利用するには次のようにします。

     ~/appledoc -p プロダクト名 -c 会社名 ディレクトリ

実際の利用例は次のようになります。

     ~/appledoc -p DropFiler -c Safx --keep-undocumented-objects --keep-undocumented-members DropFiler

これを実行するだけでXcode Organizerから自動で認識されてドキュメントが参照できるようになります。 なお、--keep-undocumented-objectsと--keep-undocumented-membersがないとドキュメントがないオブジェクトとメンバが出力されなくなるので注意が必要です。

ドキュメントの記述方法

パラメータの指定などはJavaDocやDoxygenに似ており、ドキュメント自体の記述はMarkdown風です。

  • 複数行コメントは/** コメント */、単一行コメントは/// コメント

  • 同じクラス内のメンバへのリンクは自動で行われるので、initWithObjects:forKeys:のようにそのまま書けばよい

  • 他のクラスのメンバにリンクを付けたいときは[NSDictionary count]のように[]で囲む

  • 関数の引数は@param 変数名 説明、戻り値は@return 説明

  • グルーピングは@name セクションタイトル

    /// @name Accessing Keys and Values

記述や出力の例として、appledocのソースをappledocでドキュメント化したものがありますので、そちらも参考にしてください。

注意点

  • JavaDocのようにコメントの最初の1文が概要になるのではなく、最初のパラグラフが概要になる
  • --no-repeat-first-parを指定しないと最初のパラグラフもDiscussionに記述されてしまう
  • 日本語を含むときには、リンクしたい変数などの前後はスペースを入れる (リンクとして認識されないときがある)

関連リンク

ラベル: , ,

0 件のコメント:

コメントを投稿

注: コメントを投稿できるのは、このブログのメンバーだけです。

登録: コメントの投稿 (Atom)