コマンドラインで作るAPIリファレンスの作成方法
Objective-Cとして書いています。MacOSXにはDeveloperToolsKitにHeaderdoc2htmlというコマンドが梱包されています。これは、Appleが作成したAPIドキュメントを作るためのコマンドで、C系のコメント（/*..*/）から必要な情報を抜き出して、ドキュメントに仕上げるコマンドです。なおここではさらっとしか書きません。
コマンド
コマンドラインで使用します。
[yasui@MacMini: ~/Desktop/ReinRous][19:24] $ open ReinRous/ [yasui@MacMini: ~/Desktop/ReinRous][19:24] $ headerdoc2html -o ReinRous Rein\ Rous\ iPhone/ Documentation will be written to ReinRous HTML output mode. ======= Parsing Input Files ======= Processing Rein Rous iPhone/main.m Skipping. No HeaderDoc comments found. ... Processing Rein Rous iPhone/Classes/Rein_Rous_iPhoneViewController.m Skipping. No HeaderDoc comments found. ...done [yasui@MacMini: ~/Desktop/ReinRous][20:06] $
タグ
専用のタグを使います。例1のようにコメントを書けば、内部のコメントを取り出し、headerdocは自身のタグと理解し読み込みます。タグの先頭には@が付き、@tagという文法で一行で書きます。注意として、タグではないが「@」を使う場合は「\@」とエスケープする必要があります。日本語などのマルチバイト文字は使えます。
/*! */
例1 HeaderDocが読み込むコメントの記述
具体例クラス編
以下、ガイドラインに記載されている例で説明します。
例2,例3,例4は、それぞれObjective-Cのinterface,Protocol,Categoryのタグ説明の方法です。「@class」 にインターフェース名を書きます。同様に、Protocolには「@protocol」、Categoryには「@category」と書きます。「@discussion」に作成方法などのサンプルを書きます。「@class」「@protocol」「@category」「@discussion」それぞれ引数を一つ持ち、それぞれのタグに合わせた説明を書きます。以降の部分は説明文になります。内にはHTMLタグが書けたかと思います*1。
/*! @class myInterface @discussion This is a discussion. It can span many lines or paragraphs. */ @interface myInterface : NSObject @end
例2 : インターフェースのクラス説明
/*! @protocol myProtocol @discussion This is a discussion. It can span many lines or paragraphs. */ @protocol myProtocol @end
例2 : プロトコルの説明
/*! @category myCategory(myMainClass) @discussion This is a discussion. It can span many lines or paragraphs. */ @interface myCategory(myMainClass) @end
例3 : カテゴリーの説明
例5は、Objective-Cのメソッドの説明の書き方です。「＠method」「@abstract」「@discussion」「@param」「@result」タグそれぞれ、メソッド名、概要、使用例、パラメーター、返り値を引数に書きます。
/*! @method dateWithString:calendarFormat: @abstract Creates and returns a calendar date initialized with the date specified in the string description. @discussion [An extended description of the method...] @param description A string specifying the date. @param format Conversion specifiers similar to those used in strftime(). @result Returns the newly initialized date object or nil on error. */ + (id)dateWithString:(NSString *)description calendarFormat:(NSString *)format;
例5 : メソッドの説明
具体例define,const,enum,struct編
例6は、define文の説明です。「@defined」「@abstract」「@discussion」はそれぞれ、define名、説明、使用例、以降に補足説明です。注意すべきは「@parseOnly」で、このタグがあるdefine文は非公開であるという意味になります。
/*! @defined TRUE @abstract Defines the boolean true value. @parseOnly @discussion Extended discussion goes here. Lorem ipsum.... */ #define TRUE 1
例6 : defineの説明
例7はconst変数の説明です。「@const」「@abstract」「@discussion」はそれぞれ、変数名、説明、使用例、補足説明です。
/*! @const kCFTypeArrayCallBacks @abstract Predefined CFArrayCallBacks structure containing a set of callbacks appropriate... @discussion Extended discussion goes here. Lorem ipsum.... */ const CFArrayCallBacks kCFTypeArrayCallBacks;
例7 : constの説明
例8はenumの説明です。「@enum」「@discussion」「@constant」は他同様、列挙体名、使用例、列挙名、以降に補足説明です。
/*! @enum Beverage Categories @abstract Categorizes beverages into groups of similar types. @constant kSoda Sweet, carbonated, non-alcoholic beverages. @constant kBeer Light, grain-based, alcoholic beverages. @constant kMilk Dairy beverages. @constant kWater Unflavored, non-sweet, non-caloric, non-alcoholic beverages. @discussion Extended discussion goes here. Lorem ipsum.... */ enum { kSoda = (1 << 6), kBeer = (1 << 7), kMilk = (1 << 8), kWater = (1 << 9) }
例8 : 列挙体の説明
例9は構造体の説明です。「@struct」「@abstruct」「@field」「@discussion」はそれぞれ、構造体名、説明、フィールド名、使用例、補足説明です。
/*! @struct TableOrigin @abstract Locates lower-left corner of table in screen coordinates. @field x Point on horizontal axis. @field y Point on vertical axis @discussion Extended discussion goes here. Lorem ipsum.... */ struct TableOrigin { int x; int y; }
例9 : 構造体の説明
*1:未確認
