Inline tagletを用いたjavadocのNLS化手法

ページオプション JavaScript を要するドキュメントオプションは表示されません サンプルコード

レベル: 初級

高橋 弘一, ソフトウェア開発研究所, IBM
宮島 広之, ソフトウェア開発研究所, IBM

2006年 1月 20日

javadocドキュメントのNLS化方法として、inline tagletで言語タグを定義し、その言語タグを用いてjavaソース内に複数の言語でコメントを記述し、javadocコマンド実行時に言語を指定して、指定した言語のドキュメントを取得する手法について説明します。

たとえば、日本で開発したアプリケーションを日本および世界で販売する場合、一般的に日本語と英語のドキュメントが必要です。先に述べたような方法を用いると、以下のようなメリットがあります。

• アプリケーションのソース、日本語のドキュメントのソース、および英語のドキュメントのソースがすべてJavaソース内に記述されることになり、3 つのソースを一元管理できる
• Javaソースと、日本語のコメント、英語のコメントの相互参照が容易である。つまり、それぞれのチェックを行いやすい

はじめに

ｊavadocドキュメントをNLS化する一般的な方法は、 ある言語 (主言語) で生成されたjavadocドキュメントをその他の言語 (副言語) に翻訳することです。 たとえば、javaソース内に英語でコメントを記述し、そこからjavadocコマンドで英語のドキュメントを生成し、 英語のドキュメントをその他の言語に翻訳する、 という方法です。 Ja-Jakarta Project[1]で利用されているSUNのLocalization Doclet[2] もこの方法の一種です。 こういった翻訳によるNLS化方法では、 主言語と副言語の扱いが異なります。 そして、主言語のユーザー/開発者にとっては、副言語の人たちに比べメリットがあります。 たとえば、主言語のドキュメントは副言語のそれに比べソースに対してより忠実であると思われます。 また主言語の開発者にとっては、 ソース内に理解できる言語でコメントが記述されているので便利です。

javadocドキュメントのNLS化方法として、javaソース内で言語タグを用いて複数の言語でコメントを記述し、 javadocコマンド実行時に言語を指定して、指定した言語のドキュメントを取得するというアイディアがあります[3]。 このサイトには具体的な実現方法は記述されていませんが、 議論の内容からdoclet[4] で実現しようとしていると思われます。しかしdocletを用いてこのアイディアを実現するのは容易ではありません。この場合、まず以下のようなデザインから始める必要があります。

1. どのようなhtmlを生成するか?
2. html内のレイアウトはどうするか?
3. html内の「コンストラクタの詳細」のようなタイトルのNLS化はどうするか?

また開発においては、 htmlファイルの作成、 言語タグの解析、 @returnなどの既存のタグの処理など、 すべてdocletで行わなければいけません。

このアイディアをもっと簡単に実現する方法として、inline tagletで言語タグを定義する手法について説明します([3]が書かれた当時tagletはありませんでした)。

ところで、このようにJavaソース内に複数の言語でコメントを記述すれば、先に述べたような主言語、副言語の区別はなくなります。Javaソース内に、プログラム・コードとすべての言語のjavadocドキュメントのソースが記述されることになるので、それらが一元管理されることになります。また、プログラム・コードとすべての言語のコメントの相互参照が容易になります。

上に戻る

Inline tagletを用いて言語タグを定義する手法

Inline tagletを用いる手法の詳細

inline tagletで言語タグを定義し、 [3]のアイディアを実現する手法について、 日本語と英語のコメントを併記する場合を例にとって説明します。

1. 言語タグの定義

inline tagletの規則に従い、 たとえば英語のタグを {@.en } と、 日本語のタグを {@.ja } を定義します。

2. 言語タグの内容を有効/無効にするtagletの定義

図1は. enタグの内容を有効にするtaglet（EnOnTaglet.java） のコードの一部です。 toString() メソッドは .enタグ内の文字列をそのまま返します。 一方、 図2は .enタグの内容を無効にするtaglet（EnOffTaglet.java） のコードの一部です。 toString() メソッドは常に文字列 ”” を返します。

                
public class EnOnTaglet implements Taglet {
    private final static String TAG_NAME = ".en";
    public static void register(Map tagletMap) {
        EnOnTaglet tag = new EnOnTaglet();
        tagletMap.put(TAG_NAME, tag);
    }
    public String toString(Tag tag) {
        return tag.text();
    }
    …
}

                
public class EnOffTaglet implements Taglet {
    private final static String TAG_NAME = ".en";
    public static void register(Map tagletMap) {
        EnOffTaglet tag = new EnOffTaglet();
        tagletMap.put(TAG_NAME, tag);
    }
    public String toString(Tag tag) {
        return "";
    }
    …
}

同様に、 .jaタグを有効にするtaglet JaOnTaglet.javaと無効にするtaglet JaOffTaglet.javaを定義します。

3. 言語タグを用いたコメントの併記

言語タグを用いて図3のように、 javaソース内に日本語と英語のコメントを併記します。

                
public class CounterClass{
    /**
     * {@.en Default Constructor.}
     * {@.ja デフォルト・コンストラクター。}
     * @param counter 
     *   {@.ja カウンターの初期値}
     *   {@.en initial value of counter}
     * @throws IllegalArgumentException 
     *   {@.en counter is negative.}
     *   {@.ja counterが負の値です。}
     */
    public CounterClass(int counter){
        …
    }
    …
}

4. NLS化されたjavadocの取得

日本語ロケールの実行環境において、図3のjavaソースから、 英語のjavadocドキュメントを取得する場合は(a)のように、 日本語のドキュメントを取得する場合は(b)のようにtagletを組み合わせてjavadocコマンドを実行します。

(a) javadoc -locale en_US -taglet EnOnTaglet -taglet JaOffTaglet …

(b) javadoc -taglet JaOnTaglet -taglet EnOffTaglet …

(a) により図4のような英語のドキュメントが、 (b) により図5のような日本語のドキュメントが生成されます。

この手法では、 「はじめに」で述べたdocletを用いる場合のようなデザイン、 開発の作業はすべてjavadocコマンド自体が行うことになるので、docletに比べ容易にアイディア[3] を実現できます。

上に戻る

注意点、課題

inline tagletを用いる手法を適用する場合の注意点、 課題について説明します。

1. javadocで最初から定義されているinlineタグはtagletで処理しなくてはいけない

図1の例では実装していませんが、 たとえば表1のように {@. ja } 内でinlineタグ {@link …} を用いる場合、 {@link …} のアンカー・タグへの変換はtagletで行わなければなりません。

2. コメント文の境界について

javadocはコメント文の境界を解析し[5]、 コメント文を分割した後inlineタグの部分をtagletに渡しています。 このため開始タグ、たとえば ”{@.ja”、 と終了タグ ”}” が同じ文内に見つからなければエラーとなります。 つまり、 解析結果で分離される一文より長い文章を１つの言語タグで囲むことはできません。

また、 javadocではコメントの最初の文が概要に用いられています。 複数の言語のコメントを併記した場合、 概要を正しく作成させるためには文の配置に注意が必要です。 日英のコメントを併記する場合、 たとえば図6のように配置すると概要が正しく生成されます。

                
/**
* {@.en The first English sentence.}
* {@.ja日本語の１番目の文。}
* {@.en The second English sentence.}
* {@.ja日本語の2番目の文書。}
*/

3. javaソースの読みやすさについて

javaソース内に複数の言語でコメントを記述すると確かにソースは読みにくくなります。 この問題は、 たとえばエディターに、 指定された言語以外のコメントを折りたたんで表示する機能があれば解決すると考えます[6]。

上に戻る

Appletクラスの定義例

Applet.javaは、com.applet.Appletクラスの英語と日本語のjavadocドキュメント[7][8]を生成するjavaソースの定義例です。Java 1.4.2において、このソースからコマンド(a)、(b)により実際に生成された英語のjavadocドキュメントがen/index.html、日本語のjavadocドキュメントがja/index.htmlです。

上に戻る

まとめ

javadocドキュメントのNLS化方法として、inline tagletを用いて言語タグを定義し、その言語タグを用いてjavaソース内に複数の言語でコメントを記述し、 javadocコマンド実行時に言語を指定して、 その言語のドキュメントを取得するという手法を説明しました。

上に戻る

ダウンロード

	ダウンロード形式について

参考文献

• [1] Ja-Jakarta Project
  
  
• [2] Javadoc FAQ
  
  
• [3] Java House Mailing List
  
  
• [4] Javadoc 5.0 ツール
  
  
• [5] BreakIterator
  
  
• [6] Folding in Eclipse Text Editors
  
  
• [7] Applet API(英語)
  
  
• [8] Applet API(日本語)
  

著者について

		高橋弘一は、ソフトウェア開発研究所の開発エンジニアです。主に金融関係のアプリケーションを開発しています。

		宮島広之は、ソフトウェア開発研究所のアーキテクトです。エージェント・サーバー技術を応用したエージェント・フレームワークやテンプレート・エンジンを利用したソリューションのアーキテクチャーを構築しています。

記事の評価

サイト改善のため、ご意見をお寄せください。こちらのフォームからお願いいたします。 この情報はお客様が目的を達成するうえで役に立ちましたか？ はい いいえ わからない   お気軽にご意見・ご感想をお寄せください。   この記事は役に立ちましたか？ 1 2 3 4 5 不充分・不完全である 大変素晴らしい

上に戻る