目次


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

第 2 回 JavaTOC ドックレットを使って生成する Eclipse Javadoc API リファレンス構造

Comments

コンテンツシリーズ

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

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

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

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

概要

連載の第 1 回「Eclipse ヘルプにJava API リファレンス・マニュアルを編成する方法」では、使いやすくて検索ができる Java アプリケーション・プログラミング・インターフェース (API) のリファレンス・マニュアルを作成する方法を紹介しました。

今回の記事では、JavaTOC ドックレット・ツールの使い方と拡張方法を説明します。ここで取り上げる方法では、Javadoc による標準的なソリューションと、私が開発した JavaTOC ドックレットを使って作成した Eclipse プラグインのヘルプ・システムを使います。JavaTOC ドックレット・ツールは、Eclipse ヘルプ・システムに必要な XML 目次 (TOC) ナビゲーション・ファイル、そして HTML 形式の Sun Javadoc API リファレンス・マニュアルを生成します。この方法を理解できるよう、この記事には Sun Javadoc と JavaTOC ドックレット・ツールを使用したサンプル・デモ (コマンド・プロンプトを使用) を付属させてあります。

JavaTOC ドックレットを使って生成する Eclipse Javadoc API リファレンス構造

設計上の制約

JavaTOC ドックレットと Javadoc を実行すると、Java API リファレンス・マニュアル、目次 (TOC) ナビゲーション、そしてプラグイン構造を生成することができます。あるいは JavaTOC ドックレットだけを実行し、開発者から提供された既存のマニュアルから TOC ナビゲーションを生成することも可能です。

作業の流れ

Eclipse ヘルプ・システム (Java API リファレンス・セクション) に寄与するプラグインのそれぞれについて、基本的には以下の流れに従って処理を行います。

JavaTOC ドックレットを実行して、Eclipse ヘルプ・システムに必要なすべてのプラグイン・ファイル (plugin.xml、primary.plugin.toc.xml、META-INF/MANIFEST.MF、build.properties、および plugin.properties) を作成します。

  • org.eclipse.help.toc 拡張ポイントを拡張する plugin.xml ファイルには、以下のものが指定されている必要があります。
    1. 1 つの TOC XML ファイル (少数の Java パッケージしかない場合)
    2. 複数の TOC XML ファイル (Java パッケージが多数ある場合)
  • Java ソース・コード・ファイルで Javadoc (Sun Microsystems, Inc.) を実行し、Java API リファレンス・マニュアル用の HTML ファイルを作成します。
  • 作成された Java API リファレンス・マニュアルをテストします。

Ant は、最近ではほとんど誰もが使用している Java ビルド・システムです。Ant で作業した経験がない方は、Jakarta Web サイトまたは「Open Source Java: Ant」を参照してください。

JavaTOC ドックレット・ツールを実行する方法としては、個人的には Ant ビルド・システムを使用する方を選びますが、この記事ではコマンド・プロンプトから JavaTOC ドックレットを使用する方法を紹介します。

コマンド・ラインから TOC XML ファイル出力を作成する方法

JavaTOC Doclet Toolkit リリース 1.0.0 には、Ant をよく知らないユーザーでも簡単にツールキットを使えるようにコマンドライン・インターフェースが用意されています。

  1. Javadoc がパスに組み込まれていることを確認します (...\jdk1.5.0_06\bin\javadoc.exe)。
    • 注: 通常、Javadoc のパスは C:\Program Files\Java\jdk1.5.0_06\bin のようになります。
  2. JavaToc Doclet ZIP ファイルをダウンロードして、任意のディレクトリー (Windows の場合は C:\doclet\ など) に解凍します。ファイルが解凍されると、JavaTOC ディレクトリーとそのサブディレクトリーである bin\、demo\、doc\ が作成されます。
    • bin ディレクトリーには、doc 拡張を jar ライブラリーとして実行するために必要な Java クラスが含まれています (DocletTOC.jar)。
    • doc ディレクトリーには、JavaTOC User Guide および HTML 形式の org.dita.dost.doc プラグインの API マニュアル (サンプル) が含まれています。
    • src リソース・ディレクトリーには、このサンプルに使用できる Java ソース・ファイルが含まれています。
      (これらのソース・ファイルは、SOURCEFORGE Web サイトから直接ダウンロードできます (DITA-OT1.3_src.zip)。)
  3. @packages オプションを使って、パッケージの完全修飾型名を別個のファイルに配置します。
  4. ディレクトリー c:\doclet からコマンド javadoc @tocdoclet @options @packages を実行します (リスト 1 からリスト 3)。
リスト 1. tocdoclet
 -doclet com.ibm.malup.doclet.config.TOCDoclet
-docletpath C:\doclet\bin\TOCNavDoclet.jar
リスト 2. options
-sourcepath src
-d com.ibm.doc_plugin_name
-overview src/overview-summary.html
-doctitle 'Navigation label'
-version 'plugin_version' -pluginid plugin_id
-provider 'plugin_provider_name' 
-anchor 'plugin_name'
リスト 3. packages
com.ibm.package1
com.ibm.package2
...
com.ibm.packageN
リスト 4. removefiles
source\..\..\package1\fileA.java,source\..\..\package2\fileB.java, , ,
source\..\..\packageN\fileN.java
  1. これらのファイルを変更するには、NotePad エディターでファイルを開きます。
    • JavaTOC ドックレットがプラグインの名前、ID、バージョン、そしてプロバイダー名の値を Eclipse プラグイン・プロジェクトに渡します (リスト 2 を参照)。
      org.eclipse.help.toc プラグインの拡張ポイントは、このプラグインをヘルプ・システムのプラグインとして識別します。
      doclet.toc.xml ファイルは、このプラグインの目次として参照されます。このファイルが、Eclipse ヘルプ・ウィンドウの左ペインに表示される階層化された情報のデータを提供することになります。
    • packages ファイルには、リスト 3 に示すような内容が含まれます。
  2. javadoc @tocdoclet @options @packages @removefiles コマンドを実行して、公開したくないすべてのクラスを削除します (リスト 4)。

JavaTOC ドックレットが提供するサポート・パラメーターの表

パラメーター説明
--d <destination directory (宛先ディレクトリー)>生成される文書の宛先ディレクトリーを指定します。デフォルトでは、カレント・ディレクトリー (パス名 "." で指定されたディレクトリー) が宛先ディレクトリーとなります。
-doclet <class (クラス)>代替ドックレットによって出力を生成します。
ドックレットを実行するには、Javadoc コマンドラインで -doclet <class (クラス)> オプションを使用してドックレット・クラスを指定する必要があります。
-sourcepath <pathlist (パスリスト)>ソース・ファイルの検索先を指定します。

デフォルトでは、src がカレント・ディレクトリーとなります。

-docletpath <path (パス)>ドックレット・クラス・ファイルの検索先を指定します。
-doctitle <html-code (HTML コード)> eclipse titleEclipse プラグインのタイトルを組み込みます。
このタイトルは、manifest.mf ファイルに以下のように反映されます。
Plugin.name = Building MDA RXE
-overview <file (ファイル)>overview 文書 (HTML ファイル) の検索先を指定します。
eclipse title
eclipse title
—version <plug-in_version (プラグインのバージョン)>プラグインのバージョン ID 詳細を指定します
eclipse title
eclipse title
—provider <plug-in_provider (プラグインのプロバイダー)>プラグインのプロバイダー名詳細を指定します。
-anchorリンクは、目次への完全修飾参照によって指定されます。以下はその一例です。
<toc link_to="../the_other_plugin_id/path/to/toc.xml#anchor_id"/>eclipse title
eclipse title
-notree

org.eclipse.help.toc コントリビューションは、対象とするヘルプの構造と、その構造に他のプラグインが寄与するヘルプを統合した構造とを含む関連 XML ファイルを 1 つ以上指定します。

プロジェクト全体のマニュアルを作成する場合は、複数の TOC XML ファイルが作成されるように指定してください。
注: このフラグ・パラメーターがない場合、作成される TOC XML ファイルは 1 つだけとなります。
  1. ドックレットは c:\doclet\com.ibm.doc_plugin_name (現在のプラグイン・ディレクトリー) に、プラグインの出力 XML ファイルと数々の有用なファイルを作成します。これらのファイルは以下のとおりです。
    • plugin.xml
    • plugin.properties
    • .project
    • META-INF\MANIFEST.MF
    • com.ibm.packageN.toc.xml - ヘルプ・ブラウザーにナビゲーション・ツリーを作成するための TOC XML ファイル
    • buildJavaDoc.xml - Ant 環境から JavaDoc ツールを実行するための ANT ファイル
    • buildJavaDoc.bat - JavaDoc ツールを実行するための BAT ファイル
  2. コマンド・プロンプト (buildJavaDoc.bat) から JavaDoc を実行して、API マニュアルの HTML ファイルを作成します。

JavaTOC ドックレットで 1 つの TOC XML ファイルを作成する方法

ドックレットについての説明は以上として、今度は実際の例で詳細を検討していきましょう。ここではサンプルとして、JavaTOC ドックレットで DITA-OT 1.3 ソース・ファイル (DITA-OT1.3_src.zip) を処理します。

TOC ファイルは、個々の HTML ファイルにマッピングされたラベル付きトピックを定義することによって重要なエントリー・ポイントを HTML コンテンツ・ファイルに定義し、一連の HTML コンテンツに対する目次のように機能します。TOC ファイルは HTML コンテンツのナビゲート方法を記述することから、ナビゲーション・ファイルと呼ばれることもあります。1 つのプラグインには、1 つ以上の TOC ファイルを含められます。

org.dita.dost サンプルを実行する

bat ファイル、C:\doclet\JavaTOC>TOCDoclet_dost.bat を実行します (リスト 5 からリスト 8)。

リスト 5. TOCDoclet_dost.bat
javadoc @config @options @packages
リスト 6. config
-doclet com.ibm.malup.doclet.config.TOCDoclet -docletpath C:\doclet\bin\TOCNavDoclet.jar
リスト 7. options
-sourcepath demo/src
-d demo/output/org.dita.dost.doc
-overview demo/src/overview-summary.html
-doctitle 'Building DITA output'
-pluginid org.dita.dost.doc
-provider XYZ
-version 1.0.1
リスト 8. packages
org.dita.dost.index
org.dita.dost.invoker
org.dita.dost.log
org.dita.dost.module
org.dita.dost.pipeline
org.dita.dost.platform
org.dita.dost.reader
org.dita.dost.util
org.dita.dost.writer
org.dita.dost.exception

または、C:\doclet\JavaTOC ディレクトリーからコマンド・プロンプト (C:\doclet\JavaTOC>) で以下のコマンドを実行します。

javadoc -doclet com.ibm.malup.doclet.config.TOCDoclet -docletpath C:\doclet\JavaTOC\bin\TOCNavDoclet.jar -sourcepath demo/src -d demo/output/org.dita.dost.doc -doctitle 'Building DITA output' -pluginid org.dita.dost.doc -provider XYZ -version 1.0.1 -overview demo/src/overview-summary.html org.dita.dost.index org.dita.dost.invoker org.dita.dost.log org.dita.dost.module org.dita.dost.pipeline org.dita.dost.platform org.dita.dost.reader org.dita.dost.util org.dita.dost.writer org.dita.dost.exception

出力ファイルの宛先ディレクトリー

  • ドックレットは C:\doclet\JavaTOC\output\org.dita.dost.doc (現在のプラグイン・ディレクトリー) に、プラグイン用の出力 XML ファイルと数々の有用なファイルを生成します。生成されるファイルは以下のとおりです (リスト 9)。
    • plugin.xml
    • plugin.properties
    • .project
    • META-INF\MANIFEST.MF
    • org.dita.dost.doc_toc.xml - ヘルプ・ブラウザーにナビゲーション・ツリーを作成するための TOC XML ファイル
    • buildJavaDoc.xml - Ant 環境から JavaDoc ツールを実行するための ANT ファイル
    • buildJavaDoc.bat - JavaDoc ツールを実行するための BAT ファイル
リスト 9. plug-in.xml
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.0"?>


<!-- ========================================================== -->
<!-- This plug-in declares an online help                       -->
<!--  contribution for IBM Rational Software Modeler.           -->
<!--  Licensed Materials - Property of IBM                      -->
<!-- (c) Copyright IBM Corp. 2006. All Rights Reserved.         -->
<!-- ========================================================== -->

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

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

</plugin>

-d、-doctitle、-version、および -provider プロパティーから、プラグインの名前、ID、バージョン、プロバイダー名の値が自動生成されます (リスト 10)。

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

プラグインのマニフェスト・ファイルはストリングをキー (%pluginName など) に置き換えてストリングを外部化し、plugin.properties ファイルに pluginName = "Online Help Sample Plugin" という形式のエントリーを作成します (リスト 11)。

リスト 11. META-INF\MANIFEST.MF
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Doc Plug-in
Bundle-SymbolicName: -pluginid; singleton:=true 
Bundle-Version: 1.0.0
Bundle-Activator: -pluginid.DocPlugin
Bundle-Localization: plugin
Require-Bundle: org.eclipse.ui,
 org.eclipse.core.runtime
Eclipse-AutoStart: true

org.eclipse.help.toc プラグインの拡張ポイントは、このプラグインをヘルプ・システムのプラグインとして識別します。doclet.toc.xml ファイルは、このプラグインの目次として参照されます。このファイルが、Eclipse ヘルプ・ウィンドウの左ペインに表示される階層化された情報のデータを提供することになります。


1 つの単純なファイルに、リスト 12 に記載するような内容が含まれます。

リスト 12. org.dita.dost.doc_toc.xml
<?xml version="1.0" encoding="UTF-8"?>

<?NLS TYPE="org.eclipse.help.toc"?>

<toc label="Building DITA output">
   <topic label="Overview" href="overview-summary.html">
  <topic label="org.dita.dost.index Package" href="../index/package-summary.html">
    <topic label="IndexTerm" href="../index/IndexTerm.html"/>
    <topic label="IndexTermCollection" href="../index/IndexTermCollection.html"/>
    <topic label="IndexTermTarget" href="../index/IndexTermTarget.html"/>
    <topic label="TopicrefElement" href="../index/TopicrefElement.html"/>
  </topic>
  <topic label="org.dita.dost.invoker Package" href="../invoker/package-summary.html">
    <topic label="AntInvoker" href="../invoker/AntInvoker.html"/>
    <topic label="CommandLineInvoker" href="../invoker/CommandLineInvoker.html"/>
    <topic label="JavaInvoker" href="../invoker/JavaInvoker.html"/>
  </topic>
  <topic label="org.dita.dost.log Package" href="../log/package-summary.html">
    <topic label="DITAOTBuildLogger" href="../log/DITAOTBuildLogger.html"/>
    <topic label="DITAOTEchoTask" href="../log/DITAOTEchoTask.html"/>
    <topic label="DITAOTFailTask" href="../log/DITAOTFailTask.html"/>
    <topic label="DITAOTFileLogger" href="../log/DITAOTFileLogger.html"/>
    <topic label="DITAOTJavaLogger" href="../log/DITAOTJavaLogger.html"/>
    <topic label="LogConfigTask" href="../log/LogConfigTask.html"/>
    <topic label="MessageBean" href="../log/MessageBean.html"/>
    <topic label="MessageUtils" href="../log/MessageUtils.html"/>
  </topic>
  <topic label="org.dita.dost.module Package" href="../module/package-summary.html">
    <topic label="Content" href="../module/Content.html"/>
    <topic label="AbstractPipelineModule" href="../module/AbstractPipelineModule.html"/>
    <topic label="ContentImpl" href="../module/ContentImpl.html"/>
    <topic label="DebugAndFilterModule" href="../module/DebugAndFilterModule.html"/>
    <topic label="GenMapAndTopicListModule" href="../module/MapAndTopicListModule.html"/>
    <topic label="IndexTermExtractModule" href="../module/IndexTermExtractModule.html"/>
    <topic label="ModuleFactory" href="../module/ModuleFactory.html"/>
    <topic label="MoveIndexModule" href="../module/MoveIndexModule.html"/>
    <topic label="MoveLinksModule" href="../module/MoveLinksModule.html"/>
  </topic>
  <topic label="org.dita.dost.pipeline Package" href="../pipeline/package-summary.html">
    <topic label="AbstractPipelineInput" href="../pipeline/AbstractPipelineInput.html"/>
    <topic label="AbstractPipelineOutput" href="../pipeline/AbstractPipelineOutput.html"/>
    <topic label="AbstractFacade" href="../pipeline/AbstractFacade.html"/>
    <topic label="PipelineFacade" href="../pipeline/PipelineFacade.html"/>
    <topic label="PipelineHashIO" href="../pipeline/PipelineHashIO.html"/>
  </topic>
  <topic label="org.dita.dost.platform Package" href="../platform/package-summary.html">
    <topic label="IAction" href="../platform/IAction.html"/>
    <topic label="DescParser" href="../platform/DescParser.html"/>
    <topic label="Features" href="../platform/Features.html"/>
    <topic label="FileGenerator" href="../platform/FileGenerator.html"/>
    <topic label="ImportAction" href="../platform/ImportAction.html"/>
    <topic label="InsertAction" href="../platform/InsertAction.html"/>
    <topic label="Integrator" href="../platform/Integrator.html"/>
    <topic label="IntegratorTask" href="../platform/IntegratorTask.html"/>
  </topic>
  <topic label="org.dita.dost.reader Package" href="../reader/package-summary.html">
    <topic label="AbstractReader" href="../reader/AbstractReader.html"/>
    <topic label="AbstractXMLReader" href="../reader/AbstractXMLReader.html"/>
    <topic label="DitamapIndexTermReader" href="../reader/DitamapIndexTermReader.html"/>
    <topic label="DitaValReader" href="../reader/DitaValReader.html"/>
    <topic label="GenListModuleReader" href="../reader/GenListModuleReader.html"/>
    <topic label="IndexTermReader" href="../reader/IndexTermReader.html"/>
    <topic label="ListReader" href="../reader/ListReader.html"/>
    <topic label="MapIndexReader" href="../reader/MapIndexReader.html"/>
  </topic>
  <topic label="org.dita.dost.util Package" href="../util/package-summary.html">
    <topic label="CatalogParser" href="../util/CatalogParser.html"/>
    <topic label="CatalogUtils" href="../util/CatalogUtils.html"/>
    <topic label="Constants" href="../util/Constants.html"/>
    <topic label="DITAOTCopy" href="../util/DITAOTCopy.html"/>
    <topic label="FileUtils" href="../util/FileUtils.html"/>
    <topic label="IsAbsolute" href="../util/IsAbsolute.html"/>
    <topic label="StringUtils" href="../util/StringUtils.html"/>
  </topic>
  <topic label="org.dita.dost.writer Package" href="../writer/package-summary.html">
    <topic label="AbstractWriter" href="../writer/AbstractWriter.html"/>
    <topic label="AbstractXMLWriter" href="../writer/AbstractXMLWriter.html"/>
    <topic label="CHMIndexWriter" href="../writer/CHMIndexWriter.html"/>
    <topic label="DitaIndexWriter" href="../writer/DitaIndexWriter.html"/>
    <topic label="DitaLinksWriter" href="../writer/DitaLinksWriter.html"/>
    <topic label="DitaWriter" href="../writer/DitaWriter.html"/>
    <topic label="JavaHelpIndexWriter" href="../writer/JavaHelpIndexWriter.html"/>
    <topic label="PropertiesWriter" href="../writer/PropertiesWriter.html"/>
  </topic>
  </topic>
  </toc>

これでプラグイン・ファイルはすべて揃い、Eclipse ヘルプ・システム用のタグが付けられました。この Java API リファレンス・マニュアルの構造では、XML 文書として作成された目次 (TOC) を使用して Eclipse ヘルプ・プラグインをナビゲートすることができます。このように XML を使って情報を構造化するという方法で、ブラウズも検索も可能であるというニーズに対応します。


このマニュアルは、左側が折り畳み可能な索引、右側が HTML 文書という形で表示されます。

JavaDoc を実行して HTML ファイルを作成する

C:\doclet\JavaTOC\demo\output\org.dita.dost.doc ディレクトリー (buildJavaDoc.bat) でコマンド・プロンプトから JavaDoc を実行し、API リファレンス・マニュアルの HTML ファイルを作成します。

C:\doclet\JavaTOC\demo\output\org.dita.dost.doc>javadoc -sourcepath src -d doc -doctitle "Building DITA output" -overview src\overview.html org.dita.dost.index org.dita.dost.invoker org.dita.dost.log org.dita.dost.module org.dita.dost.pipeline org.dita.dost.platform org.dita.dost.reader org.dita.dost.util org.dita.dost.writer org.dita.dost.exception

JavaTOC ドックレットで複数の TOC XML ファイルを作成する方法

通常 1 つの Java API は 7 つ以上のパッケージ・ファイルで構成することができます。JavaTOC ドックレットでは、1 つのファイル (package.txt) を管理するだけで、残りのファイルが生成されます。このように JavaTOC がプラグインのヘルプ・コードをすべて自動的に生成してくれるので、ヘルプ・コードを作成する時間が大幅に短縮され、API のドキュメント化に専念することができます。

同じ org.dita.dost サンプルを実行する

C:\doclet\ ディレクトリーから、コマンド・プロンプト C:\doclet\JavaTOC>javadoc @tocdoclet options.org.dita.dost @packages で JavaTOC ドックレットを実行します (リスト 13)。

リスト 13. options.org.dita.dost
 -sourcepath demo/src
-d demo/output2/org.dita.dost.doc
-overview src/overview-summary.html
-provider XYZ -doctitle 'Building DITA output'
-notree

上記では、-notree パラメーターを用いています。

パラメーター説明
-notree複数の TOC XML ファイルを作成するよう指定します。
注: このパラメーターがない場合、作成される TOC XML ファイルは 1 つだけとなります。

または以下を実行します。

C:\doclet\JavaTOC>javadoc -doclet com.ibm.malup.doclet.config.TOCDoclet -docletpath C:\doclet\JavaTOC\bin\TOCNavDoclet.jar -sourcepath demo/src -d demo/output/org.dita.dost.doc -doctitle 'Building DITA output' -pluginid org.dita.dost.doc -provider XYZ -version 1.0.1 -overview demo/src/overview-summary.html -notree org.dita.dost.index org.dita.dost.invoker org.dita.dost.log org.dita.dost.module org.dita.dost.pipeline org.dita.dost.platform org.dita.dost.reader org.dita.dost.util org.dita.dost.writer

出力ファイルの宛先ディレクトリー (org.dita.dost.doc)

  • ドックレットは c:\doclet\com.ibm.doc_plugin_name (新しいプラグイン・ディレクトリー) に、プラグインの出力 XML ファイルと数々の有用なファイルを作成します。これらのファイルは以下のとおりです。
    • plugin.xml
    • plugin.properties
    • META-INF\MANIFEST.MF
    • doclet.toc.xml
      org.dita.dost.index.toc.xml,
      org.dita.dost.invoker.toc.xml,
      org.dita.dost.log.toc.xml,
      org.dita.dost.module.toc.xml,
      org.dita.dost.pipeline.toc.xml,
      org.dita.dost.platform.toc.xml,
      org.dita.dost.reader.toc.xml,
      org.dita.dost.util.toc.xml,
      org.dita.dost.writer.toc.xml - 以上はヘルプ・ブラウザーにナビゲーション・ツリーを作成するための TOC XML ファイルです。
    • buildJavaDoc.xml - Ant 環境から JavaDoc ツールを実行するための ANT ファイル
    • buildJavaDoc.bat - JavaDoc ツールを実行するための BAT ファイル

org.dita.dost.index.toc.xml ファイルも目次にすぎないため、他のすべての toc.xml ファイルとまったく同じ形式にしなければなりません (リスト 14)。

リスト 14. 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>

上記にある「doclet.toc.xml」はプライマリー・ファイルです。ここで重要な点は、この目次をプライマリー toc として定義することです (リスト 15)。

リスト 15. 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>

この方法を使った場合と追加の topic 要素を直接組み込んだ場合 (リスト 16) とでは、マニュアルを表示したときに何の違いもありません。

リスト 16. 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="~/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="~/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 マニュアルの編集またはソース・コード・ファイルへの追加が済んだら、マニュアルを生成して期待どおりの結果になることを確認する必要があります。

プラグインをプラットフォームの plugins ディレクトリーにドロップし、Eclipse を起動して Help -> Help Contents を選択してください。

JavaDoc を実行して HTML ファイルを作成する

このサンプル (org.dita.dost) の Java API リファレンス・マニュアル (HTML 形式) を作成する方法には、以下の 2 通りがあります。

  • コマンドを実行して Java コードで javadoc ユーティリティーを実行します。
  • buildJavaDoc.bat バッチ・ファイル (リスト 17) を実行します。
リスト 17. buildJavaDoc.bat
 javadoc -sourcepath src -d doc -doctitle "DITA XML" -overview src\overview.html
org.dita.dost.index org.dita.dost.invoker org.dita.dost.log
org.dita.dost.module org.dita.dost.pipeline org.dita.dost.platform
org.dita.dost.reader org.dita.dost.util org.dita.dost.writer
org.dita.dost.exception

プラグインのパッケージ化

最終的なマニュアルでは、各 topic 要素はナビゲーション・リスト内のエントリーで表されます。これらのトピックはネストすることが可能で (つまり、1 つのトピックに複数のトピックを含めることが可能)、それぞれのトピックが 1 つの HTML ファイルを指します。トピックのネスト作業が終わったら、後はすべてのものを図 1 に示す構造にパッケージ化するだけです (プラグイン・ディレクトリーの名前は、plugin.xml に定義されたプラグインの id 属性と version 属性と一致することに注意してください)。

図 1. プラグイン・ディレクトリー
プラグイン・ディレクトリー
プラグイン・ディレクトリー

便宜上の理由から、またファイルのサイズを小さくするために、Elipse では実際のマニュアル (HTML ファイル) 全体を doc.zip という名前の ZIP ファイルに保持することができ、図 2 に示すディレクトリー構造を使用することができます。

図 2. doc.zip のディレクトリー構造
doc.zip のディレクトリー構造
doc.zip のディレクトリー構造

マニュアルを表示する

プラグインをテストするのに最も簡単な方法として、まずインストールされている Eclipse プラットフォームの plugins ディレクトリーに上記のディレクトリー全体をドロップし、それから Eclipse を起動して Help > Help Contents を選択してください。すると、追加されたプラグインがヘルプ・ウィンドウに表示されるはずです (図 3 のような表示)。

図 3. Help - Eclipse SDK
Help - Eclipse SDK
Help - Eclipse SDK

注意事項

この記事に記載した情報はテクニカル・ライターとしての私の意見と手法であり、公式な IBM テストを受ける前の「現状のまま」の状態です。そのため、明示または黙示を問わず一切の保証はありません。

JavaTOC ドックレットは著者の Mariana Alupului が発明した公開済みのツールです。この発明は IBM の知的財産の一部であり、 www.ip.com で公開されています。

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

まとめ

この記事で紹介した JavaTOC ドックレットは、HTML と少数の追加文書要素をベースに Java API リファレンス・ヘルプ・マニュアルを作成するために使用できます。このドックレットを使用すれば、Eclipse プラットフォームの文書を作成し、さらにその文書を使って既存の Eclipse ヘルプ・システムの XML および HTML 出力形式を作成することもわけありません。JavaTOC ドックレットを使って Eclipse プラットフォームの文書を開発する方法については、この記事で説明しました。この無料のオープンソースによるソリューションは文書開発を単純化し、ドックレットを操作するだけで自動的にプラグインとリファレンス・マニュアルを生成できるようにします。時が経つにつれ、マニュアルの内容はますます増えていくはずです。

developerWorks の XML ゾーンに掲載予定の連載記事、「JavaTOC ドックレットと ANT を実行して生成する Eclipse Javadoc API リファレンス構造」では、Eclipse プラグイン・ヘルプ・システム用の DITAdoclet ツールを使用して、検索可能な Java API マニュアル (TOC ナビゲーション) を自動的に生成するプロセスについて説明します。また、Java API 技術をさらに掘り下げ、Java DITA API 特殊化機能とその使用方法を含め、付加価値を付けた IBM による拡張についてより詳しく説明する予定です。


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


関連トピック

  • Sun Microsystems の Javadoc ツールについての詳細は、以下で学ぶことができます。
    • Sun Microsystems の Javadoc ツールについての詳細は、Javadoc ホーム・ページを参照してください。
    • Doclet.com で、Javadoc ツールの Doclet 拡張機能のリポジトリーを調べてください。
    • Sun のチュートリアル「How to Write Doc Comments for the Javadoc Tool」では、Javadoc の規約と理念を説明しています。
    • Javadoc ドックレット API を使用すると、Javadoc コメントから HTML、XML、DITA といった異なる形式の文書を作成するカスタム Javadoc プラグインを作成することができます。
  • developerWorks XML ゾーンで XML に関する資料を調べてください。ここには XML 関連のアプリケーションを最大限活用できるように開発者を支援する記事、チュートリアル、そしてヒントが文字通り数百と紹介されていますが、新しいトピックで独自の方法を見つけたいという読者にとっても興味深い情報となるはずです。
  • Eclipse プラットフォームに関する資料を他にも調べてください。Eclipse はオープン・ソース・コミュニティーで、そのプロジェクトはソフトウェア作成用の拡張可能な開発プラットフォームとアプリケーション・フレームワークを提供することに重点を置いています。
    • Javadoc 生成ウィザードでは Javadoc generation を生成することができます。このウィザードは javadoc.exe ツールのユーザー・インターフェースで、Java JDK に用意されています。
  • DITA Open Toolkit は、OASIS DITA Technical Committee による DITA (Darwin Information Typing Architecture) DTD およびスキーマに関する仕様の実装です。このツールキットは DITA コンテンツ (マップとトピック) を配布可能な形式に変換します。
  • DITA API Specialization (javaapiref0.8.zip) は、汎用 API リファレンス仕様を拡張する方法の一例として使用、または検討できます。
  • この連載「Javadoc API リファレンス・マニュアル」の第 1 回目の記事

コメント

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

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=60
Zone=Rational, Open source
ArticleID=284750
ArticleTitle=Java API リファレンス・マニュアル: 第 2 回 JavaTOC ドックレットを使って生成する Eclipse Javadoc API リファレンス構造
publish-date=12262007