@todo
) とインラインタグ (たとえば {@underline}
) の両方をサポートします。(「ブロックタグとインラインタグ」を参照してください。)タグレット API は、次の 1 つのインタフェースと 2 つの abstract クラスで構成されています。
Taglet
インタフェースBaseExecutableMemberTaglet
クラスBaseInlineTaglet
クラスタグレットは、-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.0
と想定しています。
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
次に、ブロックタグレットおよびインラインタグレットの例について説明します。
@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 出力に書式指定されます。
Fix this! |
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[])
メソッド (タグの 1 配列を取得する) では、複数の {@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 出力に書式指定されます。
Fix this! |
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[])
メソッド (タグの 1 配列を取得する) では、複数の {@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)
メソッドでは、{@underline}
タグに遭遇したとき、テキストをどのように出力に挿入するかを決定します。このコードは、HTML 下線タグ <ul>
および </ul>
でテキストを囲みます。
public String toString(Tag tag) { return "<u>" + tag.text() + "</u>"; }
ブロックタグの場合とは違って、インタインタグの配列を処理することはできません。そのため、インラインタグでは、toString(Tag[])
メソッド (タグの 1 配列を取得する) は無視されます。
エラー - タグレットは、エラーメッセージを表示し、System.exit()
を呼び出すだけで、エラーを報告し、Javadoc ツールを停止できます。
警告 - タグレットは、ドックレットインスタンスで指定された MessageRetriever を使用して、警告を報告できます。MessageRetriever は Configuration オブジェクトから取得されます。Configuration オブジェクトはドックレットから取得されます。たとえば、タグレットが標準ドックレットで使用するように設計されている場合、Configuration は static メソッドである Standard.configuration()
を使用して取得できます。例として、SimpleTaglet
はこのようにして警告を出力します (これは -tag
オプションのデフォルトタグレット)。