MergeDoc

Fork

MergeDoc
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

実行環境: JRE5.0 以上
URL： http://mergedoc.sourceforge.jp/

Eclipse は日本語化しても Java 標準 API のメソッドなどにマウスを合わせたときにホ
バー表示される説明は日本語化されません。これは Eclipse が JDK 付属の Java ソース
から Javadoc コメントを取得し表示しているためです。MergeDoc は日本語のホバー表示
を可能にするために Java ソースと日本語 API ドキュメントをマージするツールです。

またホバー表示以外にも次のような場合に参照するソースもコメントが日本語になります。

- Java 標準 API のメソッドを Ctrl + 左クリック
- Java 標準 API の例外スタックトレースからジャンプ
- パッケージエクスプローラから rt.jar を辿ってクラスファイルを開く

################################################################################
#
# MergeDoc のバージョンの対応について
#
# MergeDoc 1.x.x = JDK1.4 以前の javadoc で作成された API ドキュメントに対応
# MergeDoc 2.x.x = JDK5.0 以降の javadoc で作成された API ドキュメントに対応
#
# API ドキュメントが作成された javadoc コマンドのバージョンに依存しています。
# Java ソースのバージョンは無関係です。
#
################################################################################



使用方法
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

インストール

mergedoc.zip を適当な場所に解凍してください。

以前のバージョンがある場合は置換定義ファイルを上書きしてしまうのでカスタマイズ
している場合は事前に退避してください。

また 1.2.8 以前とはディレクトリ構成が異なるので上書きしないようにしてください。



アンインストール

ディレクトリごと削除してください。



起動方法

Windows で JAR ファイルに JRE/JDK5.0 以上の javaw を関連付けている場合は
mergedoc.jar ダブルクリックで起動します。また mergedoc.jar のショートカットで
も起動出来ます（ショートカット用のアイコンは \conf\icon.ico）。

[Windows での jar ファイル関連付け設定例]

"c:\jdk1.5.0\jre\bin\javaw.exe" -jar "%1" %*

それ以外の場合は次のようなコマンドで起動してください。

java -jar mergedoc.jar

MergeDoc の場合、-server オプションも合わせて指定することで、高速化されるよう
です。


起動オプション

-Dtarget.directory=ディレクトリ名

ターゲットディレクトリに入力ソースアーカイブファイルがある有効なディレクト
リを指定することで設定画面にデフォルトのファイル名が初期値としてセットされ
ます。

例）java -jar -Dtarget.directory=C:\jdk1.5.0 mergedoc.jar

API ドキュメントは JDK インストールディレクトリ内に配置しておくことをお勧
めします。このオプションにより API ドキュメントディレクトリも検出されます。
また、このオプションを指定しなかった場合でも、API ドキュメントディレクトリ
設定時に入出力アーカイブファイルが自動で検出されます。

例）C:\jdk1.5.0\docs\ja\api\



操作方法

起動後の設定画面で設定を行い実行ボタンを押下してください。
ファイルやディレクトリはドラッグ＆ドロップ可能です。


基本設定

* API ドキュメントディレクトリ

日本語 API ドキュメントを格納しているディレクトリを指定。
package-list ファイルがあるディレクトリです。

例）C:\jdk1.5.0\docs\ja\api

J2SE 5.0 日本語 API ドキュメントの場合、エンコーディングは EUC-JP に
してください。 ~~~~~~


* 入力ソースアーカイブファイル

Java ソースアーカイブファイルを指定。
ファイル形式は「.zip」「.jar」「.tar.gz」「.tgz」のいずれか。

例）C:\jdk1.5.0\src.zip

エンコーディングは JDK の場合、ASCII 以外の文字が含まれていないので
何でもかまいません。


* 出力ソースアーカイブファイル

ソースを出力する新しいアーカイブファイルを指定。
ファイル形式は「.zip」「.jar」のいずれか。

例）C:\jdk1.5.0\srcja_MS932.zip

エンコーディングは使用するエディタや IDE の設定に合わせてください。
Eclipse の場合はテキスト・ファイル・エンコードと同じにします。プロジェ
クトによってエンコードが異なる場合は srcja_MS932.zip、srcja_EUC-JP.zip
などのように複数のファイルを作成しておくと良いと思います。



詳細設定

出力ソースの調整を行います。設定をカスタマイズする場合は conf ディレクト
リの global.xml を参照してください。


API ドキュメントディレクトリを省略して実行することで Java ソースファイルの文字
コードの変換のみを行うことが可能です。その場合でも詳細設定は適用されます。なお
その他のファイルは文字コード変換も詳細設定も適用せずそのまま出力します。

例えばマージ済みの srcja_EUC-JP.zip を元に srcja_MS932.zip を作成することが出
来ます。マージに比べ、コード変換のみのほうがかなり高速です。



Eclipse で使用する場合の設定

メニューから [ウィンドウ] - [設定] - [インストール済みのJRE] の
編集画面で rt.jar のツリーを開き、Java ソースの添付でロケーションパスに
MergeDoc で作成した出力ソースアーカイブファイルを指定してください。

プロジェクト毎に設定したい場合はパッケージエクスプローラから JRE システム・
ライブラリー内の rt.jar を右クリックしてプロパティを開き Java ソースの添付を
行ってください。



補足:

J2SE5.0 日本語 API ドキュメント（2004年12月公開）は、既に元の Java ソースと
内容がかみ合わない部分があります。これらはマージ結果に以下のような影響が
あります。

1. クラス階層の不一致

例えば Java ソース上は StringBuilder や StringBuffer の親クラスは
AbstractStringBuilder ですが、API ドキュメントでは親クラスは Object に
なっており AbstractStringBuilder が存在しません。また、メソッドなどの
ページ内リンクが動作せず、HTML フォーマットもなぜか他のクラスとかなり
異なるようです。

Java ソース上のコメントは AbstractStringBuilder に記述され、サブクラスと
なる StringBuffer などの Javadoc コメントは省略（継承）されています。

このようなクラスはコメントのマッチングが不可能なためマージはほとんど
行われません。

2. <pre> タグ内の改行情報の欠落

例えば String や Thread などのクラスコメントに記述されている <pre> タグ内
コードの改行情報が欠落し 1 行になっています。これはブラウザで確認すること
ができます。

今のところ MergeDoc では元の Java ソース <pre> タグ内容を使用することで
この問題を回避しています。

2.1.3 (2006.10.28)
- アノテーション宣言の引数に配列がある場合、日本語されない問題を修正
- アノテーション・メンバのコメントが日本語されない問題を修正
（上記 2 つに影響があるのは java.lang.SuppressWarnings のみ）

2.1.2 (2006.07.09)
- 新しい JDK1.5 API ドキュメントによる StringBuffer の行数ずれを解消

2.1.1 (2005.07.23)
- コメントを小さくするときの整形を見栄えが良くなるように修正
- タイトルバーの進捗率が更新されない場合があるのを修正

2.1.0 (2005.07.10)
- Java ソースにコメント本文が無い場合、タグコメントが日本語化されない場合が
あったのを修正
- 最小化時でも進捗が分かるようにタイトルバーに進捗率を表示
- Tomcat 5.5.9 Servlet 2.4 API ドキュメントに対応

2.0.5 (2005.01.04)
- java.util.concurrent で UI レスポンスをアップ
- java.util.regex.Pattern をキャッシュし、高速化

2.0.4 (2005.01.03)
- コメント末尾に余計な空白が入る場合があるのを修正
- readme の -server が JRE のみという誤りを修正

2.0.3 (2004.12.31)
- @link が Generics や 可変長引数に一部未対応だったのを修正
- コメント本文以外の Javadoc タグの内容も見やすいように整形するようにした。
- 行数合わせの空行を一部コメント内に追加するようにした。
- core を高速化（Hyades で確認）
- readme の起動方法に -server の簡単な説明追記

2.0.2 (2004.12.23)
- Javadoc の author タグの値が複数行の場合の対応を追加
- オリジナルソースとの行数ずれを修正

2.0.1 (2004.12.22)
- ログレベルが debug になっていたのを修正

2.0.0 (2004.12.19)
- バージョン 1.2.8 を元に JDK5.0 用に修正 (Generics, Enum, Metadata 対応他)
- <table> や <ul> タグなどを見やすいように整形
- 拡張子 tgz を tar.gz 同様の扱いにした。