Header Doc

TopPage

OCUnit

HeaderDoc

GNUstep

Xcode

EmacsWiki

PageList

ChangeLog

概要

スクリプトの実行

headerDoc2HTML.plの実行

gatherHeaderDoc.plの実行

Mac Perlでスクリプトを実行させる

設定ファイル

HeaderDocコメントとタグ

ヘッダーファイルに関わるタグ

言語別のタグ

[[HeaderDoc_C_TagSet]]

[[HeaderDoc_Objective-C_TagSet]]

[[HeaderDoc_C++_TagSet]]

概要

単純なHeaderDocのコメントは以下のようになります．関数にHeaderDoc形式でコメントをつけています．

/*!
  @function        HMBalloonRect
  @discussion      Use HMBalloonRect to get information about the size of
                   a help balloon before the Help Manager displays it.
  @param inMessage The help message for the help balloon. 
  @param outRect   The coordinates of the rectangle that encloses the help
                   message. The upper-left corner of the rectangle has the
                   coordinates (0,0).
*/
OSErr HMBalloonRect (const HMMessageRecord *inMessage, Rect *outRect);

OSErr HMBalloonRect (const HMMessageRecord *inMessage, Rect *outRect);

Parameters

さらに、gatherHeaderDocも含まれています． これはheaderDoc2HTMLによって生成されたすべてのドキュメンテーションのためのマスター目次を作成するユーティリィティ・スクリプトです． gatherHeaderDocの実行についての情報は次のセクションの中で説明します．

スクリプトの実行

headerDoc2HTML.plの実行

>headerDoc2HTML.pl  MyHeader.h

上記のような単一の入力ファイルを指定する代わりに、入力ディレクトリーを指定することもできます。HeaderDocはすべての'.h'を処理します． 入力ディレクトリーを再帰的にファイルを検索して、HeaderDocコメントを含んでいるヘッダーごとのHTMLファイルの出力ディレクトリーの生成します。

出力用の別のディレクトリーを指定したい場合は以下のように"-o"スイッチで指定する事ができます．

> headerDoc2HTML.pl -o /tmp MyHeader.h

> headerDoc2HTML.pl  -q MyHeader.h
> headerDoc2HTML.pl  -qo /tmp MyHeader.h

注意)-qオプションは現在のバージョンでは使えないようです．ターミナルへの出力がうるさい場合は以下のように/dev/nullへ出力すると良いでしょう．

#headerDoc2HTML.pl -o /tmp MyHeader.h > /dev/null

HeaderDocの構成するモジュールのバージョンをHeaderDocに報告させるスイッチ、"-v"が使えます．これはHeaderDocのバグを報告するための使う事ができます．

headerDoc2HTML.pl -v

gatherHeaderDoc.plの実行

このスクリプトは headerDoc2HTML によって生成された任意のドキュメンテーションが入ったディレクトリーを与えられると、入力ディレクトリー再帰的に走査します。 それは目次ページをを作成します。

(目次ページの名前はデフォルトでMasterTOC.htmlです．コンフィグファイルで指定すると別のファイル名に変更できます．)また、すべてのドキュメンテーションに目次ページへのナビゲーションを容易にするための、トップリンクを追加します．

(スクリプトと共に提供されるサンプルもの) 配付ファイルに同封されていたサンプルコードのドキュメンテーションを作る例を示します． この例は複数のヘッダーファイルを読み込みドキュメントと目次を生成します．

> headerDoc2HTML.pl -o OutputDir ExampleHeaders
> gatherHeaderDoc.pl OutputDir

ファイル OutputDir/MasterTOC.html を開くとブラウザで目次と各々のドキュメントへのリンクを見る事ができます．

Mac Perlでスクリプトを実行させる

• Change the line endings in the scripts and modules (.pm files) from UNIX to Macintosh. Many text editors (BBEdit, for example) let you easily change line ending types.
• Run MacPerl, open headerDoc2HTML.pl and gatherHeaderDoc.pl and save them as droplets. You might save them with a different names (say, the script names minus the '.pl' extensions) to preserve the original versions.
• Now, you can drag a header file or folder of header files on each droplet in turn, and the files will be processed in place.

設定ファイル

• copyrightOwner
  HTMLのフッターに著作権のある通知はページをつけます。もしあなたが値を指定しなければ、著作権は表示されません。
• defaultFrameName
  frameset指示(デフォルト、index.htmlによる)を含んでいるファイルの名前。
• compositePageName
  印刷可能なHTMLページ(デフォルトは CompositePage.html )を含んでいるファイルの名前。
• masterTOCName
  一連のヘッダの目次を集めたマスターファイルのファイル名．(この変数はgatherHeaderDocスクリプトで使われます)
• apiUIDPrefix
  HTMLの中のハイパーリンクのプリフェックス名(デフォルトではapple_refになっています)． HTMLではHeaderDocが、各API宣言の近くの自己について記述する指定されたアンカーを加えます。 例えば <a name="//apple_ref/c/func/CFArrayAppendValue"> のように，これらはインデックス生成および他の目的に役立つことができます。より多くの情報のためのHTMLに基づいたドキュメンテーションに関しては、シンボル・マーカーを参照してください

HeaderDocは以下の順番で、上記の変数に対する値のための3つの場所のファイルを見ます:

• スクリプト自体の中。(headerDoc2HTMLのトップの近くの%configハッシュの宣言を参照)
• ユーザのホームディレクトリーの中"~/Library/Preferences/com.apple.headerDoc2HTML.config"
• スクリプトと同じフォルダー中のheaderDoc2HTML.configと命名されるファイルの中．

変数は、これらの場所のうちのどこでも設定する事ができます。しかし、与えられた変数のために読まれた最後のファイルの値だけが、スクリプトの実行の出力に影響します。これらの変数(上に記述された)に対するデフォルト価値に満足していれば、設定ファイルを提供する必要がありません。あなたが単に1つ以上の値を変更したい場合は、単なるそれらの値を宣言する設定ファイルを提供してください。

設定ファイルのフォーマットは以下のようになっています

key1 => value1
key2 => value2

以下に設定ファイルのサンプルを示します．

###################################################################
# Sample configuration file for HeaderDoc2HTML and gatherHeaderDoc
###################################################################
copyrightOwner         => My Great Software Company
defaultFrameName       => default.html
compositePageName      => PrintablePage.html
masterTOCName          => TOCCentral.html
apiUIDPrefix           => greatSoftware

HeaderDocコメントとタグ

HeaderDocコメントの形式はこんな感じです:

/*!
  @function             FunctionName
  @discussion           This is a comment about FunctionName.
*/

それらの最も単純な形式(上記例)では、それらが、2点だけで標準のCコメントと異なります:

• アスタリスクマークの次に"!"文字を追加します
• APIタイプを表明する行に@で始まるタグを追加します．(例えば@function)

さらに、特定のフィールドを識別するためにHeaderDocコメントの中に追加の JavaDoc のようなタグを使用することができます。これらのタグはコメントをHTMLへの転換にするのを助けます。 例えばより多くの完全なコメントがこのように見えるかもしれません:

/*! 
  @function             HMBalloonRect
  @abstract             Reports size and location of help ballon.
  @discussion           Use HMBalloonRect to get information about the size 
                        of a help balloon before the Help Manager displays it.
  @param      inMessage The help message for the help balloon.
  @param      outRect   The coordinates of the rectangle that encloses the 
                        help message. The upper-left corner of the rectangle 
                        has the coordinates (0,0).
*/

タグは、"@"文字によって示されます。(@はホワイトスペースを抜かしたその行の最初の文字です)

コメント中の第1のタグはAPIタイプの宣言(function、struct、enumなど)を発表します。次の2行のライン(@abstractや@discussionタグ)は、全体としてAPI要素に関するドキュメンテーションを提供します。@abstractは簡略なリストの中で使用することができ、API要素に関する詳細なドキュメンテーションの中で@discussionを使用することができます。

@abstractと@discussionタグはオプションであすが使う事を推奨されます。それらの使用は、簡略なページのようなHTML出力における様々な改良を可能にします。 タグが、それが仮定されるAPIタイプ・タグおよび名前(@function HMBalloonRectの上に)に続くテキストに付けられていない場合はabstractとして処理します。そのようなタグが付けられていないテキストで、HeaderDocは、どちらが最初に生じても次のHeaderDocタグへの、あるいはHeaderDocコメントの終了へのAPIタイプコメントの終了からabstractが伸びると仮定します。

HeaderDocは、コメントのスタイルのいくつかの変形を理解します。特にこのような1-ラインコメントを持つことができます:

/*! @var      settle_time Latency before next read. */

そして、多重ラインコメントの各ライン上でアスタリスクマークを使用する事ができます．

/*! 
 * @function              HMBalloonRect
 * @abstract              Reports size and location of help ballon.
 * @discussion            Use HMBalloonRect to get information about the size of
 *                        a help balloon before the Help Manager displays it.
 * @param      inMessage  The help message for the help balloon.
 * @param      outRect    The coordinates of the rectangle that encloses the
 *                        help message. The upper-left corner of the rectangle
 *                        has the coordinates (0,0).
 */

/*! 
 * @function              HMBalloonRect
 * @discussion            Use HMBalloonRect to get information about the size of 
 *                        a help balloon before the Help Manager displays it.
 *
 *                        By checking the help balloon size before display, you
 *                        can guard against...
 */

...HTML出力で2つのパラグラフとしてフォーマットされるでしょう:

By checking the help balloon size before display, you can guard against...

ヘッダーファイルに関わるタグ

@headerタグのために与える値は、headerDoc2HTMLによって生成されたHTMLページのタイトルとして役立ちます。@headeタグに関連させるテキストは、スクリプトが生産するHTMLウェブサイトの導入のページで使用されます。

Example:

/*!
  @header Repast Manager
  The Repast Manager provides a functional interface to the repast driver. 
  Use the functions declared here to generate, distribute, and consume meals.
*/

言語別のタグ

HeaderDoc_C_TagSet

HeaderDoc_Objective-C_TagSet

HeaderDoc_C++_TagSet