Hatena::ブログ(Diary)

おおたに6号機blog このページをアンテナに追加 RSSフィード

2009-07-17(金)

[]JavaDoc i18nにする方法 16:39 JavaDoc i18nにする方法を含むブックマーク


T2JavaDocのために、幾つかJavaDoci18nにする方法を試してみましたのでここに書いてみる。

何をやろうとしているかというと、JavaDoc英語日本語両方で出力したいという割と単純かつよくありそうな要望です。


localized docletを使う方法

最初に試したのがこれ。Doclet拡張ですね。

簡単に言うと、日本語部分には{@.ja }、英語部分には{@.en }で括る。

記事としてはこれが最初に読んだやつです。



プロダクトとしてはid:skimuraさんが出しているのでこちらを利用しました。ありがとうございます。


メリット

比較的簡単に使えます。私はmaven2から使っていたので、maven-javadocプラグインに以下のように設定して、

mvn javadoc:javadocするだけで使えます。

        <plugin>
          <artifactId>maven-javadoc-plugin</artifactId>
          <configuration>
            <source>1.6</source>
            <encoding>UTF-8</encoding>
            <docencoding>UTF-8</docencoding>
            <charset>UTF-8</charset>
            <locale>ja_JP</locale>
            <links>
              <link>http://java.sun.com/javase/6/docs/api/</link>
            </links>
            <taglets>
              <taglet>
                <tagletClass>jp.dodododo.javadoc.doclet.localization.LanguageTaglet</tagletClass>
                  <tagletArtifact>
                    <groupId>jp.dodododo.localization-doclet</groupId>
                    <artifactId>localization-doclet</artifactId>
                    <version>0.1.0</version>
                  </tagletArtifact>
              </taglet>
            </taglets>
          </configuration>
        </plugin>


デメリット

1行以上の長い文章がちゃんと処理されないです。多分Docletのそもそものつくりが悪いんじゃないかと予想。

なので、1行ずつ{@.jaとかで括る必要が出てきます。割とがっつり書きたい・書こうと思ってる人にはちょっと不向き。


FreeMarkerを使う方法

次にやってみたのが、FreeMarker(FMPP)+Antを使って


というもの。

サイトは以下を参考にしました。ありがとうございます。


しかしながら、残念ですが上のやつだけでは現在ダメのようでした。どうやらJava5からのアノテーションまわりのJavaDocの処理が

きちんと対処されておらず、ClassCast例外でおちまくって幾つかのhtmlが出力されないという事態に陥りました。


バグとしてはまだUnfixedっぽい(困ってる人多数)・・・以下を参照。


というわけでこの対処方法としては、使ってるアノテーションクラスパスを全部javadocタスクに通してやる必要があります。

というわけでbuild.xmlがこんな感じになりました。

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<project basedir="." default="javadoc" name="t2">
	<property name="fmpp.lib" value="./javadoc-lib/fmpp.jar" />
	<taskdef name="fmpp" classname="fmpp.tools.AntTask" classpath="${fmpp.lib}" />
	<path id="javadoc.path">
		<pathelement location="target/classes" />
		<pathelement location="target/test-classes" />
		<fileset dir="javadoc-lib">
			<include name="*.jar" />
		</fileset>
		<fileset dir="lib">
			<include name="*.jar" />
		</fileset>
		<fileset dir="lib/optional">
			<include name="*.jar" />
		</fileset>
		<fileset dir="webapp/WEB-INF/lib">
			<include name="*.jar" />
		</fileset>
	</path>

	<target name="javadoc" description="Generate javadoc.">
		<mkdir dir="target/logs"/>
		<macrodef name="javadoc-i18n">
			<attribute name="locale" />
			<sequential>
				<mkdir dir="target/javadocsrc-@{locale}" />
				<fmpp sourceroot="src" outputroot="target/javadocsrc-@{locale}" data="locale:@{locale}" logfile="target/logs/log-@{locale}.fmpp">
					<exclude name="META-INF/t2.tld" />
				</fmpp>
				<javadoc source="1.6" author="true" sourcepath="target/javadocsrc-@{locale}" destdir="target/javadoc-@{locale}" windowtitle="T2 framework" Locale="@{locale}" encoding="UTF-8" package="org.t2framework.t2.*" charset="UTF-8">
					<classpath refid="javadoc.path">
					</classpath>
					<link href="http://java.sun.com/javase/6/docs/api" />
					<link href="http://java.sun.com/products/servlet/2.5/docs/servlet-2_5-mr2/index.html" />
				</javadoc>
			</sequential>
		</macrodef>

		<javadoc-i18n locale="ja" />
		<javadoc-i18n locale="en" />
	</target>
</project>



これで、ソースに以下のようなJavaDocを書いて、Antすると見事日本語JavaDoc英語JavaDocが出来上がります。


/**
 * <#if locale="en">
 * <p>
 * ActionUtil handles T2-specific things.This utility class is absolutely
 * internal class.
 * </p>
 * <#else>
 * <p>
 * ActionUtilはT2独自の処理を行います.このユーティリティクラスは、T2の内部だけで利用されるクラスです.
 * </p>
 * </#if>
 * 
 * @author shot
 */

メリット

メリットはきちんとがっつりJavaDoc書いても大丈夫なところですね。特に量書く場合はこちらの方が良いでしょう。

T2ではこちらを採用することにしました。


デメリット

デメリットとしては、JavaDoc生成に時間がかかるのと、IDEからのJavaDocの可読性が下がってしまうところです。

ここはなんとかしたいところ。




今後の課題

課題としては、以下のようなものがあります。


というわけでJavaDoci18nする人がいれば何かの参考にしてみてください。

QQOgawaQQOgawa 2009/07/20 16:26 〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜

 。。本の整理をしていたら、BEAにもらった

 ”SOA―サービス指向アーキテクチャ ”

 http://www.seshop.com/detail.asp?pid=5835

 が出てきました。まだ読んでいないのですが、
中大規模システムで、使用するには問題がある オブジェクト指向
の解決策を考えるには、良い手がかりになりそうに、見えました。

〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜

ちなみに、
まさたかさん にも関係が深い Turbo Pascal・Delphi ・C# の
アーキテクトである、
 アンダース ヘルスバーグ は副作用が強いので、AOPは使用しない
方針だそうです。

 
 http://www.microsoft.com/japan/msdn/community/person/andershejlsberg/communityreport.aspx


_________________________________