|
タグレットの概要 |
@todo) とインラインタグ (たとえば {@underline}) の両方をサポートします。「ブロックタグとインラインタグ」を参照してください。タグレット API は、次の 1 つのインタフェースと 2 つの abstract クラスで構成されています。
Taglet インタフェース
BaseExecutableMemberTaglet クラス
BaseInlineTaglet class
タグレットは、-tag オプションの基盤となる機能です。-tag オプションを使用すると、組み込みタグレットが使用されて、@return に対して生成されるのと類似したデフォルト HTML 形式が生成されます。
BaseExecutableMemberTaglet を継承
Taglet を実装
Taglet を実装
BaseInlineTag を継承
BaseExecutableMemberTaglet クラスは、Taglet を拡張したもので、インラインタグをサポートするための追加機能を提供しています。このクラスは、{@link} や {@docroot} といった標準インラインタグと、ユーザが作成するカスタムインラインタグの両方をサポートします。
HtmlStandardWriter または Doc オブジェクトにアクセスする必要のあるインラインタグを記述する場合には、BaseInlineTag を継承する必要があります。たとえば、{@value} インラインタグでは、フィールドから定数値を取得するために Doc オブジェクトが必要です。大部分のタグは、ドックレットのエラー報告メソッドを使用してエラーを報告するために HtmlStandardWriter だけを必要とします。
タグレットは、次の基本手順に従って作成し、使用します。
BaseExecutableMemberTaglet を拡張する場合であれば、次のような import 文が必要です。
import com.sun.tools.doclets.Taglet; // Taglet API import com.sun.tools.doclets.standard.tags.BaseExecutableMemberTaglet; // For inline tags import com.sun.tools.doclets.standard.HtmlStandardWriter; // For error reporting??? import com.sun.javadoc.*; // Doclet API import java.util.Map; // Used in register(Map)
toString(Tag) で使用される Tag インタフェースは、ドックレット API の一部です。
public static void register(Map tagletMap)
作成するクラスでは、さらに、そのクラスが実装するインタフェースまたは拡張するクラスで必要となるものも実装しなければなりません。toString メソッドの中に、カスタムタグに渡されるテキスト引数の修正、書式指定、またはリダイレクトを実行するためのカスタム処理を実装します。
toString(Doc, HtmlStandardWriter)
lib\tools.jar ファイルに含まれています。このあとの最初の例では、SDK のインストール先を C:\Program Files\j2sdk1.4.1 と想定しています。
javac -classpath "C:\Program Files\j2sdk1.4.0\lib\tools.jar" ToDoTaglet.java
-taglet オプションおよび -tagletpath オプションを使用して javadoc ツールを実行します。たとえば、タグレットのクラスファイルを com.sun パッケージ内に入れるように定義されており、 C:\taglets\com\sun\Taglet.class にコードが格納されている場合は、tagletpath に C:\taglets を設定します。この例では、ToDoTaglet タグが組み込まれている com.package1 パッケージを指定して javadoc を呼び出しています。
javadoc -taglet ToDoTaglet -tagletpath C:\taglets com.package1
次に、ブロックタグレットおよびインラインタグレットの例について説明します。
YET TO UPDATE BELOW HERE !!!!!!!!!!!!!!
@todoを実装する ブロックタグレットの例のソースコードは、次のファイルに含まれています。 対応するクラスファイルであるToDoTaglet.classは、すでにコンパイルされ、このソースファイルと同じディレクトリ内に保存されています。ドックレットを実行するには、
-tagletpathおよび-tagletオプションを指定します。ToDoTaglet.classが/home/user/tagletにあり、@todoタグがTest.javaファイル内にあるとすると、コマンドは次のようになります。% javadoc -d html -tagletpath /home/user/taglet -taglet ToDoTaglet ./Test.javaファイルTest.javaに次のようなドキュメンテーションコメントが含まれているとすると、/** * @todo Fix this! */ToDoタグレットによって、次のような HTML 出力に書式指定されます。
- To Do:
Fix this!
実装に関する説明
ソースコードを見てみましょう。タグに名前を付け、ヘッダテキストを定義するには、2 つの private フィールドを定義します。private static final String NAME = "todo"; private static final String HEADER = "To Do:";インラインタグではなくブロックタグにするため、isInlineTagが false を返すように設定します。public boolean isInlineTag() { return false; }ほかに、inField、inMethod、inType、inPackage、inOverviewの各メソッドでも、trueまたはfalseを指定することにより、ソースコード内でこのタグを使用できるドキュメンテーションコメントを示します。
toString(Tag)メソッドでは、1 つの{@todo}タグに遭遇したとき、テキストをどのように出力に挿入するかを決定します。このコードは、太字の見出しのあと、tag.text()で指定されたテキストを含む黄色の背景の表を作成します。public String toString(Tag tag) {` return "<DT><B>" + HEADER + "</B><DD>" + "<table cellpadding=2 cellspacing=0><tr><td bgcolor=\"yellow\">" + tag.text() + "</td></tr></table></DD>\n"; }同様に、toString(Tag[])メソッド (タグの配列を引数にとる) では、複数の{@todo}タグに遭遇したとき、テキストをどのように出力に挿入するかを決定します。
@todoを実装する ブロックタグレットの例のソースコードは、次のファイルに含まれています。 対応するクラスファイルであるToDoTaglet.classは、すでにコンパイルされ、このソースファイルと同じディレクトリ内に保存されています。ドックレットを実行するには、
-tagletpathおよび-tagletオプションを指定します。ToDoTaglet.classが/home/user/tagletにあり、@todoタグがTest.javaファイル内にあるとすると、コマンドは次のようになります。% javadoc -d html -tagletpath /home/user/taglet -taglet ToDoTaglet ./Test.javaファイルTest.javaに次のようなドキュメンテーションコメントが含まれているとすると、/** * @todo Fix this! */ToDoタグレットによって、次のような HTML 出力に書式指定されます。
- To Do:
Fix this!
実装に関する説明
ソースコードを見てみましょう。タグに名前を付け、ヘッダテキストを定義するには、2 つの private フィールドを定義します。private static final String NAME = "todo"; private static final String HEADER = "To Do:";インラインタグではなくブロックタグにするため、isInlineTagが false を返すように設定します。public boolean isInlineTag() { return false; }ほかに、inField、inMethod、inType、inPackage、inOverviewの各メソッドでも、trueまたはfalseを指定することにより、ソースコード内でこのタグを使用できるドキュメンテーションコメントを示します。
toString(Tag)メソッドでは、1 つの{@todo}タグに遭遇したとき、テキストをどのように出力に挿入するかを決定します。このコードは、太字の見出しのあと、tag.text()で指定されたテキストを含む黄色の背景の表を作成します。public String toString(Tag tag) {` return "<DT><B>" + HEADER + "</B><DD>" + "<table cellpadding=2 cellspacing=0><tr><td bgcolor=\"yellow\">" + tag.text() + "</td></tr></table></DD>\n"; }同様に、toString(Tag[])メソッド (タグの配列を引数にとる) では、複数の{@todo}タグに遭遇したとき、テキストをどのように出力に挿入するかを決定します。
ブロックタグとは違って、カスタムインラインタグは、タグレットを使用してのみ実装できます。つまり、-tagオプションを使用して実装することはできません。これは、インラインタグにはデフォルトの動作がないためです。対応するクラスファイルである
{@underline}を実装するインラインタグレットの例のソースコードは、次のファイルに含まれています。UnderlineTaglet.classは、すでにコンパイルされ、このソースファイルと同じディレクトリ内に保存されています。このタグレットは、
{@underline}タグの出力形式を指定します。次のタグを含むドキュメンテーションコメントは、/** * Be sure to insert the value at the {@underline start} of the array. */次のような HTML として出力されます。Be sure to insert the value at the start of the array.
実装に関する説明
このソースコード (インラインタグレット) と、前出の例 (ブロックタグレット) との違いを見てみましょう。もちろん、タグ名は異なり、インラインタグにはヘッダがないので定義されていません。private String NAME = "underline";ブロックタグではなくインラインタグにするため、isInlineTagが true を返すように設定します。public boolean isInlineTag() { return true; }
inField、inMethod、inConstructor、inType、inPackage、およびinOverviewの各メソッドは、ブロックタグにのみ適用されます。そのため、インラインタグではすべて false を返すように設定する必要があります。
toString(Tag)メソッドでは、1つの{@underline}タグに遭遇したとき、テキストをどのように出力に挿入するかを決定します。このコードは、HTML 下線タグ<ul>および</ul>でテキストを囲みます。public String toString(Tag tag) { return "<u>" + tag.text() + "</u>"; }ブロックタグの場合とは違って、インタインタグの配列を処理することはできません。そのため、インラインタグでは、toString(Tag[])メソッド (タグの配列を引数にとる) は無視されます。
エラー - タグレットは、エラーメッセージを表示し、System.exit()を呼び出すだけで、エラーを報告し、Javadoc を停止できます。警告 - タグレットは、ドックレットインスタンスで指定された MessageRetriever を使用して、警告を報告できます。MessageRetriever は Configuration オブジェクトから取得されます。Configuration オブジェクトはドックレットから取得されます。たとえば、タグレットが標準ドックレットで使用するように設計されている場合、Configuration は static メソッドである
Standard.configuration()を使用して取得できます。例として、SimpleTagletはこのようにして警告を表示します。これは-tagオプションのデフォルトタグレットです。
|
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved. コメントの送付先: javadoc-tool@sun.com |
|