タグレットの概要

目次

タグレット API

タグレットは、Java™ プログラミング言語で記述したプログラムであり、タグレット API を実装しています。タグレットは、ブロックタグ (たとえば @todo) とインラインタグ (たとえば {@underline}) の両方をサポートします。(「ブロックタグとインラインタグ」を参照してください。)タグレット API は、次の 1 つのインタフェースと 2 つの abstract クラスで構成されています。 タグレットを使用すると、カスタムタグのテキスト引数の修正や書式指定が可能になるほか、テキストをファイルやその他のストリームにリダイレクトすることもできます。タグレットによって標準タグをオーバーライドすることもできます。

タグレットは、-tag オプションの基盤となる機能です。-tag オプションを使用すると、組み込みタグレットが使用されて、@return に対して生成されるのと類似したデフォルト HTML 形式が生成されます。

タグレットの記述

次のうちどちらの種類のタグレットを記述するかを選んで、適切なインタフェースを実装するか、適切な abstract クラスを継承します。 BaseExecutableMemberTaglet クラスは、Taglet を継承したもので、インラインタグをサポートするための追加機能を提供しています。このクラスは、{@link}{@docroot} といった標準インラインタグと、ユーザーが作成するカスタムインラインタグの両方をサポートします。

HtmlStandardWriter または Doc オブジェクトにアクセスする必要のあるインラインタグを記述する場合には、BaseInlineTag を継承する必要があります。たとえば、{@value} インラインタグでは、フィールドから定数値を取得するために Doc オブジェクトが必要です。大部分のタグは、ドックレットのエラー報告メソッドを使用してエラーを報告するために HtmlStandardWriter だけを必要とします。

タグレットは、次の基本手順に従って作成し、使用します。

  1. タグレットとなる Java プログラムを記述します。記述するタグレットに適切な import 文を組み込みます。たとえば、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 の一部です。
  2. 実装しているインタフェース、または継承している abstract クラスで必要となるものに加えて、次の static メソッドを実装する必要があります。その後、実行時にロードされるようにタグレットを有効化します。このあとのを参照してください。
        public static void register(Map tagletMap)  
    
    
    作成するクラスでは、さらに、そのクラスが実装するインタフェースまたは継承するクラスで必要となるものも実装しなければなりません。toString メソッドは、カスタムタグに渡されるテキスト引数を修正、書式指定、またはリダイレクトするためのカスタム処理を実装する場所です。
        toString(Doc, HtmlStandardWriter)
    
  3. ドックレットをコンパイルします。それには、Java 2 SDK に含まれている javac コンパイラのバージョン 1.4.0 以降を使用します。必要なクラスファイルは、SDK の lib\tools.jar ファイルに含まれています。このあとの最初の例では、SDK のインストール先を C:\Program Files\j2sdk1.4.0 と想定しています。
       javac -classpath "C:\Program Files\j2sdk1.4.0\lib\tools.jar"  ToDoTaglet.java
    
  4. -taglet オプションおよび -tagletpath オプションを使用して Javadoc ツールを実行します。たとえば、タグレットのクラスファイルが com.sun パッケージ内に入れるように定義されており、C:\taglets\com\sun\Taglet.class に格納されている場合は、tagletpath に C:\taglets を設定してください。この例では、ToDoTaglet タグを含む、パッケージ com.package1javadoc を呼び出します。
       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 出力に書式指定されます。
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;
    }
ほかのメソッド inFieldinMethodinTypeinPackageinOverview でも、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 出力に書式指定されます。
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;
    }
ほかのメソッド inFieldinMethodinTypeinPackageinOverview でも、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;
    }

inFieldinMethodinConstructorinTypeinPackageinOverview の各メソッドは、ブロックタグにのみ適用されるため、インラインタグではすべて 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 オプションのデフォルトタグレット)。


Copyright © 1993, 2013, Oracle and/or its affiliates. All rights reserved.