タグレットの概要

タグレットAPI

タグレットは、Java(tm)プログラミング言語で記述したプログラムであり、タグレットAPIを実装しています。タグレットは、ブロック・タグ(たとえば@todo)またはインライン・タグ(たとえば{@underline})のいずれかとして記述できます。現在のところ、ブロック・タグレットは、そのテキスト内でインライン・タグをサポートしていません。(「ブロック・タグとインライン・タグ」を参照してください。)タグレットAPIは、次の1つのインタフェースで構成されています。

Tagletインタフェース

タグレットを使用すると、カスタム・タグのテキスト引数の修正や書式指定が可能になるほか、テキストをファイルやその他のストリームにリダイレクトするなど、さまざまな処理を実行できます。タグレットによって標準タグをオーバーライドすることもできます。

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

タグレットの記述

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

タグレットとなるJavaプログラムを記述します。プログラムは次のものをインポートする必要があります。
```
   import com.sun.tools.doclets.Taglet;    // Taglet API
   import com.sun.javadoc.*;               // Doclet API
   import java.util.Map;                   // Used in register(Map)
```
com.sun.javadocのクラスは、toString(Tag)で使用するTagインタフェースのためにインポートする必要があります。
作成するクラスでは、そのクラスが継承するインタフェースで必要となるものを実装しなければなりません。toStringメソッドは、カスタム・タグに渡されるテキスト引数を修正、書式指定、またはリダイレクトするためのカスタム処理を実装する場所です。
```
    public String toString(Tag tag)
```
実装しているインタフェースで必要となるものに加えて、次のstaticメソッドを実装する必要があります。その後、実行時にロードされるようにタグレットを有効化します。このあとの例にあるソース・コードを参照してください。
```
    public static void register(Map tagletMap)  
```
ドックレットをコンパイルします。それには、JDKに含まれているjavacコンパイラのバージョン1.4.0以降を使用します。必要なクラス・ファイルは、JDKのlib\tools.jarファイルに含まれています。このあとの最初の例では、JDKのインストール先をC:\Program Files\j2sdk1.4.1と想定しています。
```
   javac -classpath "C:\Program Files\j2sdk1.4.1\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.java

対応するクラス・ファイルであるToDoTaglet.classは、すでにコンパイルされ、このソース・ファイルと同じディレクトリ内に保存されています。

このタグレットは、@todoタグの出力を書式指定します。次のタグを含むドキュメンテーション・コメントは、

    /**
     * @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[])メソッド(タグの1配列を取得する)では、複数の{@todo}タグに遭遇したとき、テキストをどのように出力に挿入するかを決定します。

registerメソッドは次のとおりです。

    /**
     * Register this Taglet.
     * @param tagletMap  the map to register this tag to.
     */
    public static void register(Map tagletMap) {
       ToDoTaglet tag = new ToDoTaglet();
       Taglet t = (Taglet) tagletMap.get(tag.getName());
       if (t != null) {
           tagletMap.remove(tag.getName());
       }
       tagletMap.put(tag.getName(), tag);
    }

例 - インライン・タグレット

ブロック・タグとは違って、カスタム・インライン・タグは、タグレットを使用してのみ実装できます。つまり、-tagオプションを使用して実装することはできません。これは、インライン・タグにはデフォルトの動作がないためです。

{@underline}を実装するインライン・タグレットの例のソース・コードは、次のファイルに含まれています。

UnderlineTaglet.java

対応するクラス・ファイルである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オプションのデフォルト・タグレット)。

連絡先

タグレットの概要

目次

タグレットAPI

タグレットの記述

例 - ブロック・タグレット

実装に関する説明

例 - インライン・タグレット

実装に関する説明

エラーおよび警告の処理