目次


Java API リファレンス・マニュアル

第 1 回 Eclipse ヘルプに Java API リファレンス・マニュアルを編成する方法

Comments

コンテンツシリーズ

このコンテンツは全#シリーズのパート#です: Java API リファレンス・マニュアル

このシリーズの続きに乞うご期待。

このコンテンツはシリーズの一部分です:Java API リファレンス・マニュアル

このシリーズの続きに乞うご期待。

背景

この記事では、Java ソフトウェア、Java API リファレンス・マニュアルの構造、Javadoc の生成について十分な知識を持ち、Java API リファレンス・マニュアルの改善方法を詳しく知りたいという読者を対象としています。

初心者の場合は、以下について習熟する必要があります。

使いやすくて検索ができる Java API リファレンス・マニュアルを作成する

この記事では、使いやすくて検索ができる Java アプリケーション・プログラミング・インターフェース (API) のリファレンス・マニュアルを作成するための 2 通りの方法を説明します。ここで取り上げる方法は、Javadoc による標準的なソリューションによるものと、私が開発した JavaTOC ドックレットを使って作成した Eclipse プラグインのヘルプ・システムを使うものです。この JavaTOC ドックレットは、Javadoc API リファレンス・マニュアルの目次 (TOC) を作成して、ユーザーが特定のクラスやインターフェース、あるいはメソッドを簡単に API リファレンス・マニュアルで検索できるようにします。

Javadoc API リファレンス・マニュアルは、ブラウズと検索の両方を行えるようにする必要があります。標準の Javadoc ではこの必要を完全には満たせません。完全にドキュメント化された API はいくつかの目的を果たしますが、なかでも最も重要な目的は、ユーザーが使用できる API 関数をユーザーが十分に理解し、検索できるようにすることです。API 関数が適切にドキュメント化されていなかったり、あるいは検索できないとなると、作成した本人でさえソース・コードを理解できなくなる場合があります。これに対するソリューションは、ソース・コードを文書化するという習慣をつけ、Java API リファレンスを検索できる構造 (TOC ナビゲーション) を作成することです。JavaTOC ドックレットはリファレンスの検索ができる構造を作成することで、この問題を解決します。

検索操作とブラウズ操作では、個々の問い合わせに対する関連性を基準にして情報がソートされることを前提としており、結果的にあらゆるシーケンスを臨機応変に作成します。例えば標準の Javadoc では、特定のメソッドの説明を API 情報で検索すると、該当するクラス全体の説明が返されます。

検討する方法

Java API リファレンス・マニュアルを生成するツールにはかなりの数があります。私がここでお勧めするのは、Javadoc または DITA API 特殊化機能との組み合わせで使用する JavaTOC ドックレットです。

  • Sun が所有する Javadoc は、Java ソース・コードから開発者のコメントを抽出して HTML に出力するツールです。Javadoc ツールは Java API リファレンス・マニュアルの基本構造を生成します。その結果が、一連のパッケージとクラスに関する Javadoc の HTML API ドキュメントとなります。
  • JavaTOC ドックレットは、Java API リファレンス・マニュアルの TOC ナビゲーションと検索機能を生成します。IBM DITA API 特殊化機能チームが開発した DITA トピック・タイプのパッケージが、Java API ドキュメント・ファイル、そして Eclipse ヘルプ・システムに組み込まれるリファレンスのナビゲーション・リストを作成します。

以降に記載するサンプル (TOC ナビゲーションを使用しない場合の API リファレンスの例TOC ナビゲーションを使用した場合の API リファレンスの例) では、DITA Open Toolkitに含まれている Java ソース・コードを使用しています。DITA Open Toolkit リリース 1.0.2 以降には、コマンド・プロンプト・インターフェースが用意されているので、Ant をほとんど知らないユーザーでもこのツールキットを簡単に使うことができます。この記事のサンプルに使用したソース・コードは、ダウンロードした zip ファイルの DITA-OT1.2_src\DITA-OT1.2-src\srcディレクトリーにあります。

Javadoc と JavaTOC ドックレットについて

標準の Javadoc ヘルプとカスタマイズされた Eclipse の Javadoc ヘルプとの最大の違いは、提供される TOC ナビゲーションです。標準の Javadoc ヘルプでは、いくつかのフレームを追加してパッケージとクラスをブラウズできるようにしています。一方、カスタマイズされた Eclipse の Javadoc ヘルプには、このような追加の HTML フレームの代わりに Eclipse 形式の XML ナビゲーション・ファイルが含まれます。Eclipse 形式のこれらの XML ナビゲーション・ファイルによって、ユーザーが特定のパッケージ、クラス、またはインターフェースを検索できるようにする TOC ナビゲーションが作成されます。カスタマイズされた Eclipse の Java API リファレンスは、Eclipse ヘルプ・システムに組み込まれる文書のナビゲーション・リストを提供するソリューションです。

Eclipse プラットフォーム全体は、プラグインの概念を中心に開発されます。そのため、作成したヘルプ文書を Eclipse プラットフォームに追加するには、新しいヘルプ用のプラグインを開発しなければなりません。このプラグインを構成するのは、HTML と画像ファイル、XML 形式の目次ファイル、そしてマニフェスト・ファイルです。JavaTOC ドックレットは、Java ソース・コードから直接抽出する XML ナビゲーション TOC ファイルをはじめ、Eclipse プラグイン構造全体を自動的に生成します。

JavaTOC ドックレットは、Javadoc ツールとも連動するようにカスタマイズされたプログラムです。このドックレットの柔軟性を拡張すると、Javadoc 文書ファイルを基に TOC ナビゲーションを生成することが可能になります。

IBM DITA API 特殊化機能の場合、JavaTOC ドックレットは DITAdoclet ツールに統合されます。このツールは、Java API リファレンスの文書化および生成に必要な Java DITA (XML) API ファイルを生成するために開発されたものです。このソリューションにも、Eclipse Help System に組み込まれる Java API リファレンス・マニュアルのナビゲーション・リストが含まれます。

標準の Javadoc ツールで生成される Eclipse の Javadoc API リファレンス構造

Eclipse の標準の Javadoc オンライン・ヘルプにアクセスするには、メニュー・バーで Help > Help Contents を選択します。この操作により、オンライン・ヘルプがその固有のブラウザーに表示されます。

左のペインにはタブ付きのビューがあり、ここに目次、検索、そしてコンテキスト・センシティブ・ヘルプのリンクが表示されます。以下の図 1 は、標準の Javadoc API リファレンスのサンプル構造です。このサンプルは、Eclipse 環境で標準の Javadoc ツールだけを使用して生成されています。

図 1. Javadoc API リファレンスの構造
Javadoc API リファレンスの構造
Javadoc API リファレンスの構造

org.eclipse.help.toc の拡張ポイントでは、以下のファイルがヘルプ・システムのプラグインとして識別されます。

リスト 1. plug-in.xml
<?xml version="1.0" encoding="UTF-8"?>
 <?eclipse version="1.0"?>

 <plugin>

  <extension point="org.eclipse.help.toc">
   < toc file="doclet.toc.xml" primary="true"/>
  </extension>

</plugin>
リスト 2. MANIFEST.MF
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Doc Plug-in
Bundle-SymbolicName: org.dita.dost.doc; singleton:=true 
Bundle-Version: 1.0.0
Bundle-Activator: org.dita.dost.doc.DocPlugin
Bundle-Localization: plugin
Require-Bundle: org.eclipse.ui,
 org.eclipse.core.runtime
Eclipse-AutoStart: true

または

リスト 3. plug-in.xml
<?xml version="1.0" encoding="UTF-8"?>
 <?eclipse version="1.0"?>

 <plugin
    name = "%Plugin.name"
    id = "org.dita.dost.user.doc"
    version = "7.0.1.0"
    provider-name = "%Plugin.providerName">

  <extension point="org.eclipse.help.toc">
   < toc file="doclet.toc.xml" primary="true"/>
  </extension>

</plugin>

プラグインの名前、ID、バージョン、プロバイダー名は、それぞれのプロジェクトに合わせて変更してください。

リスト 4. plugin.properties
         # NLS_MESSAGEFORMAT_VAR
# ==============================================================================
# Online Help - Translation Instruction: section to be translated
# =============================================================================
Plugin.name = Building DITA output
Plugin.providerName = IBM

doclet.toc.xml ファイルは、このプラグインの目次として参照されます。このファイルが、Eclipse ヘルプ・ウィンドウの左ペインに表示される階層情報のデータを提供することになります。単純なファイルは、リスト 2 に示すような内容になります。

リスト 5. doclet.toc.xml
<?xml version="1.0" encoding="UTF-8"?>
 <?NLS TYPE="org.eclipse.help.toc"?>

<toc label="Building DITA output">
   <topic label="API References" href="index.html"/>
</toc>

上記の href = "index.html" は、作成された javadoc API リファレンスへのリンクです。右のペインに HTML フレームなしで文書を表示させる場合、このリンクは href="overview-summary.html"となります。

標準の Javadoc ナビゲーション・バーの構成

標準の Javadoc ナビゲーション・バーでは、ユーザーが特定のパッケージ、クラス、メソッドを検索することはできません。

図 2 は、SUN Javadoc で構成および記述される Javadoc タブのナビゲーションです。

図 2. Javadoc タブのナビゲーション
Javadoc タブのナビゲーション
Javadoc タブのナビゲーション
Overview
Overview ページは API 文書のフロントページで、ここにすべてのパッケージがそれぞれのサマリーとともにリストされます。このページには、一連のパッケージに関する概要の説明を表示することもできます。
注意:
  • パッケージ・レベルの Javadoc を Overview.html という名前を付けたファイルに書き込むことを忘れないでください。このファイルは、コード・ファイルが存在するルート・ディレクトリーに配置する必要があります。これは、Javadoc がファイルを選択し、そのコンテンツを使用できるようにするために必要です。
Package
パッケージごとに、そのパッケージのクラスとインターフェースをそれぞれのサマリーとともにリストするページがあります。このページに表示できるカテゴリーは、 Interfaces, Classes, Exceptions, Errors,Constantsの5つです。
注意:
  • パッケージ・レベルの Javadoc を package.html という名前を付けたファイルに書き込むことを忘れないでください。このファイルは、該当するパッケージのコード・ファイルが存在するディレクトリーに配置する必要があります。これは、Javadoc がファイルを選択し、そのコンテンツを使用できるようにするために必要です。
Class/Interface
クラス、インターフェース、内部クラス、そして内部インターフェースには、それぞれ固有のページがあります。各ページは、クラス/インターフェースの説明、サマリー表、そして詳細なメンバー説明を表示する 3 つのセクションで構成されます。
各サマリー・エントリーには、その項目に対する詳細説明の最初のセンテンスが含まれます。
サマリー・エントリーはアルファベット順ですが、詳細説明はソース・コードに記載された順になります。これにより、プログラマーが確立した論理的分類が維持されます。
Use
文書化されたパッケージ、クラス、インターフェースごとに固有の Use ページがあります。このページには、その特定のクラスまたはパッケージを一部でも使用しているパッケージ、クラス、メソッド、コンストラクター、およびフィールドの説明が表示されます。
Tree (クラス階層)
すべてのパッケージを対象とした Tree (クラス階層) ページ、さらにパッケージごとの階層ページがあります。それぞれの階層ページには、クラスのリストおよびインターフェースのリストが表示されます。
Deprecated
Deprecated API ページには、非推奨 API 全体がリストされます。非推奨 API とは、改善などの理由により使用が推奨されない API のことで、通常は代わりの API が表示されます。非推奨 API は、以降の実装では削除される可能性があります。
Index
Index には、クラス、インターフェース、コンストラクター、メソッド、フィールドがアルファベット順にリストされます。
Prev/Next
この 2 つのリンクは、次または前のクラス、インターフェース、パッケージ、あるいは関連ページを表示するためのものです。
Frames/No Frames
この 2 つのリンクは、HTML フレームの表示/非表示を切り替えます。すべてのページで、フレームを表示または非表示にすることができます。

JavaTOC ドックレットを使用して生成される Eclipse の Javadoc API リファレンス構造

ブラウズも検索も可能な Java API リファレンス・マニュアルのニーズに対応するのは、XML 形式などの構造化情報で Eclipse JavaTOC ドックレットと Javadoc ヘルプ形式を使用するという手法です。

Eclipse ヘルプ・プラグイン内でナビゲーションを可能にするには、情報開発者が XML 文書として作成した目次 (TOC) を提供する必要があります。この文書は、左側が折りたたみ式の索引、右側が HTML 文書という形で表示されます。これらの HTML ファイルは、Javadoc または IBM DITA Java API 特殊化機能を使用して作成できます。

TOC は手動で作成することも、JavaTOC ドックレットを使用して自動的に作成することもできます。JavaTOC ドックレットは自動的に、パッケージと各パッケージに含まれるクラスおよびインターフェースをリストした Java API リファレンスの TOC 構造を生成します。

API リファレンスの HTML ファイルを作成するには、Javadoc ツールを実行するか、あるいは IBM DITA API 特殊化機能のソリューションにより Java API リファレンス HTML ファイルのオーサリングと生成を行います (図 3)。

図 3. HTML - キット・エディター
HTML - キット・エディター
HTML - キット・エディター

JavaTOC ドックレットを使用すると、ブラウズも検索も可能な API リファレンス・マニュアルとなります。検索機能は、使用する構造化情報の手法 (XML) により実現されます。

XML を使用して API リファレンス・マニュアルの構造を作成すると、副次効果の 1 つとして、コンテンツに検索用の索引が自動的に設定されます。一方、標準の Javadoc ソリューションでコンテンツを作成する場合、デフォルトでは検索を目的としたコンテンツの索引付けは行われません。

Eclipse Java API リファレンス構造と TOC の生成に必要なファイル

ここからは、上記の Java API リファレンスの TOC ナビゲーション構造を生成するために使用したサンプル TOC XML ファイルを紹介します。これらのファイルは手動で作成することも、JavaTOC ドックレットを使用して自動的に作成することもできます。Eclipse 対応 Java API リファレンスの XML TOC サンプルをダウンロードするには、「ダウンロード」セクションを参照してください。

以下のリストは、Eclipse Java API リファレンス・プラグインのサンプルです。このサンプルは、1 つの TOC XML ファイルを参照しています。

リスト 6. plug-in.xml
<?xml version="1.0" encoding="UTF-8"?>
 <?eclipse version="1.0"?>

 <plugin>

  <extension point="org.eclipse.help.toc">

  <toc file="doclet.toc.xml" primary="true"/>

  </extension>

</plugin>

以下のリストは上記と同じ Eclipse Java API リファレンス・プラグインのサンプルですが、ここでは Java パッケージ構造に基づいて複数の TOC XML ファイルを参照しています。使用する TOC XML ファイルが 1 つの場合と複数の場合では、表示される文書に違いはありません。

リスト 7. plug-in.xml
<?xml version="1.0" encoding="UTF-8"?>
 <?eclipse version="1.0"?>

 <plugin
    name = "%Plugin.name"
    id = "org.dita.dost.user.doc"
    version = "7.0.1.0"
    provider-name = "%Plugin.providerName">

  <extension point="org.eclipse.help.toc">

   <toc file="doclet.toc.xml" primary="true"/>

    <toc file="org.dita.dost.exception.toc.xml"/>
    <toc file="org.dita.dost.index.toc.xml"/>
    <toc file="org.dita.dost.invoker.toc.xml"/>
    <toc file="org.dita.dost.log.toc.xml"/>
    <toc file="org.dita.dost.module.toc.xml"/>
    <toc file="org.dita.dost.pipeline.toc.xml"/>
    <toc file="org.dita.dost.platform.toc.xml"/>
    <toc file="org.dita.dost.reader.toc.xml"/>
    <toc file="org.dita.dost.util.toc.xml"/>
    <toc file="org.dita.dost.writer.toc.xml"/>


  </extension>

</plugin>

Eclipse 出力に、ナビゲーション・ファイルを組み込む位置、あるいは実行時にナビゲーション・ファイルを添付させる位置を設けるには、navref 要素と anchor 要素、さらに map 要素の anchorref 属性を使用します。Eclipse ナビゲーション・ファイルのオーサリングについての詳細は、Eclipse の資料を参照してください。

リスト 8. doclet.toc.xml
<?xml version="1.0" encoding="UTF-8"?>
 <?NLS TYPE="org.eclipse.help.toc"?>

<toc label="Building DITA output">
   <topic label="Overview" href="doc\overview-summary.html">
        <link toc="org.dita.dost.exception.toc.xml"/>
        <link toc="org.dita.dost.index.toc.xml"/>
        <link toc="org.dita.dost.invoker.toc.xml"/>
        <link toc="org.dita.dost.log.toc.xml"/>
        <link toc="org.dita.dost.module.toc.xml"/>
        <link toc="org.dita.dost.pipeline.toc.xml"/>
        <link toc="org.dita.dost.platform.toc.xml"/>
        <link toc="org.dita.dost.reader.toc.xml"/>
        <link toc="org.dita.dost.util.toc.xml"/>
        <link toc="org.dita.dost.writer.toc.xml"/>
 </topic>
</toc>

基本となる XML TOC にはタイトル (Eclipse ではラベル) が必要です。これは、該当するヘルプの目次がロードできるようにするためです。

org.dita.dost.index.toc.xml ファイルも同じく目次なので、他のすべての toc.xml ファイルとまったく同じフォーマットにしなければなりません。

リスト 9. org.dita.dost.index.toc.xml
<?xml version="1.0" encoding="UTF-8"?>
 <?NLS TYPE="org.eclipse.help.toc"?>

<toc label="org.dita.dost.index Package" link_to="../doclet.toc.xml#java.packages">
  <topic label="org.dita.dost.index Package" 
  href="doc/org/dita/dost/index/package-overview.html">
           <anchor id="org.dita.dost.index.packages"/>
    <topic label="IndexTerm" href="doc/org/dita/dost/index/IndexTerm.html"/>
    topic label="IndexTermCollection" 
    href="doc/org/dita/dost/index/IndexTermCollection.html"/>
    <topic label="IndexTermTarget" href="doc/org/dita/dost/index/IndexTermTarget.html"/>
    <topic label="TopicrefElement" href="doc/org/dita/dost/index/TopicrefElement.html"/>
  </topic>
</toc>

新しい API 文書の編集またはソース・コード・ファイルへの追加が終わったら、文書を生成して期待どおりの結果になることを確認してください。

Eclipse 3.2 では、doc プラグイン全体を 1 つの jar ファイルとして装備することができます。この jar ファイルには、標準プラグイン・ファイル (manifest.mf、plug-in.xml、plug-in.properties など) と一緒に doc.zip ファイルに圧縮されるすべてのファイルが含まれます。Eclipse 3.2 より前のリリースでは、静的 HTML ファイルおよび拡張ポイント・スキーマ HTML ファイルと併せて、生成した Javadoc ファイルを doc.zip ファイル内に保持することになります。

文書化されていないコードは、理解しにくかったり、あるいは理解できなくなります。また、再使用も管理もできません。JavaToc ドックレットは価値のあるツールです。この記事が、プロジェクトに JavaToc ドックレットを採り入れることを検討するきっかけとなれば本望です。

注意事項

この記事に記載した情報は、公式な IBM テストを受ける前の「現状のまま」の状態で、明示または黙示を問わず一切の保証はありません。

この情報の使用、またはこの記事に記載した手法の実装については、読者の責任であり、読者の評価能力および動作環境への統合能力に依存します。

まとめ

今後予定している記事「JavaTOC ドックレットを使って生成する Eclipse Javadoc API リファレンス構造」では、検索可能な Java API リファレンス・マニュアル (TOC ナビゲーション) をJavaTOC ドックレットと Eclipse プラグイン・ヘルプ・システムを使って自動的に生成するプロセスを説明します。また、この連載の以降の記事では Java DITA API 特殊化機能とその使用方法を含め、API 文書のオーサリングおよび生成技術、そして付加価値を付けた IBM による拡張について、より詳しく説明する予定です。


ダウンロード可能なリソース


関連トピック

  • Sun Microsystems の Javadoc ツールについての詳細は、 Javadocホーム・ページを参照してください。
  • Doclet.comで、Javadoc ツールの Doclet 拡張機能のリポジトリーを調べてください。
  • Sun のチュートリアル「How to Write Doc Comments for the Javadoc Tool」では、Javadocの規約と理念を説明しています。
  • Java 言語では、Javadoc コメント規約による API 文書への統合アプローチを採用しています。David Gallardo の記事「Javaの理論と実践: それをドキュメント化しなければならないか」を読んで、プラグイン開発環境のコード生成ウィザードで Eclipse プラグインを作成する方法を学んでください。
  • IBM developerWorks の「Eclipseのヘルプ・システムを使ってプロジェクトを文書化する」を参照してください。
  • Eclipse に興味がある方にとって、Eclipse Learning Guideは有益なポインターや役に立つリンクが満載された学習の手引きとなるはずです。
  • 記事 「Eclipseでヘルプを集中化する」 では、Eclipse のヘルプとプラグイン・アーキテクチャーの動的性質を利用して集中型ヘルプ・リポジトリーを作成する方法を実例を用いて説明しています。この記事が焦点としているのは、ヘルプ目次を備えたEclipse プラグインを作成する方法、インフォメーション・センターを使用してヘルプ・ファイルを外部化する方法、そして Eclipse のメイン・メニューから集中型ヘルプ・リポジトリーに直接アクセスするための新しいメニュー項目を作成する方法です。
  • 開発者でもヘルプ・システムにアクセスしなければならないことはあります。また、時にはリモート・アクセスが必要になる場合もあります。
    記事 「Running the WebSphere Studio help system remotely」では、Angel Vera が WebSphere Studio Application Developer ヘルプ・システムを実行する方法を紹介しています。
  • IBM alphaWorks のDocumentation Enhancer for Javaは、対応する Java クラスファイルの静的分析により収集した新しい情報 (セマンティック情報、ソート、ナビゲーション機能) を追加して、Javadoc ファイルを拡張するツールです。
  • Eclipse プロジェクトのダウンロード・ページから、Eclipse Platform Plug-in SDK をダウンロードしてください。
  • Eclipse Platform コミュニティーに参加して、 eclipse.orgからこのプラットフォームをダウンロードしてください。eclipse.org には、Eclipse プロジェクトの用語集と説明、そして技術記事やニュースグループも記載されています。Eclipse プラットフォーム・ホワイト・ペーパーでは、Eclipse の主要なコンポーネントおよび機能を詳説しています。
  • developerWorks XML ゾーンには、XML 資料が豊富に用意されています。

コメント

コメントを登録するにはサインインあるいは登録してください。

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=60
Zone=Rational, Open source
ArticleID=277589
ArticleTitle=Java API リファレンス・マニュアル: 第 1 回 Eclipse ヘルプに Java API リファレンス・マニュアルを編成する方法
publish-date=03202007