Java API リファレンス・マニュアル: 第 2 回 JavaTOC ドックレットを使って生成する Eclipse Javadoc API リファレンス構造

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

レベル: 中級

Mariana Alupului (malupulu@us.ibm.com), Information Developer, Rational software, IBM

2007年 12月 26日

連載第 2 回目となるこの記事では、使いやすくて検索ができる 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 リファレンス構造

設計上の制約

極めて熟練したテクニカル・ライター (Java API 情報の作成者) になるためには、Java 言語について、そして Java 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 ファイル出力を作成する方法

コンピューター・プログラミング言語は、ソース・コードの記述の始まりと終わりを通知する特殊なシンボルを提供することによってソース・コードの文書化をサポートします。このようなシンボルと記述は、まとめてコメントと呼ばれています。Java プログラミング言語がサポートするコメントには、複数行、単一行、文書という 3 つの形式があります。

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)。

                 -doclet com.ibm.malup.doclet.config.TOCDoclet
-docletpath C:\doclet\bin\TOCNavDoclet.jar

                -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'

                com.ibm.package1
com.ibm.package2
...
com.ibm.packageN 

                source\..\..\package1\fileA.java,source\..\..\package2\fileB.java, , ,
source\..\..\packageN\fileN.java 

5. これらのファイルを変更するには、NotePad エディターでファイルを開きます。
   • JavaTOC ドックレットがプラグインの名前、ID、バージョン、そしてプロバイダー名の値を Eclipse プラグイン・プロジェクトに渡します (リスト 2 を参照)。
     org.eclipse.help.toc プラグインの拡張ポイントは、このプラグインをヘルプ・システムのプラグインとして識別します。
     doclet.toc.xml ファイルは、このプラグインの目次として参照されます。このファイルが、Eclipse ヘルプ・ウィンドウの左ペインに表示される階層化された情報のデータを提供することになります。
   • packages ファイルには、リスト 3 に示すような内容が含まれます。
6. 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 プラグインのタイトルを組み込みます。 このタイトルは、manifest.mf ファイルに以下のように反映されます。 Plugin.name = Building MDA RXE
-overview <file (ファイル)>	overview 文書 (HTML ファイル) の検索先を指定します。
—version <plug-in_version (プラグインのバージョン)>	プラグインのバージョン ID 詳細を指定します
—provider <plug-in_provider (プラグインのプロバイダー)>	プラグインのプロバイダー名詳細を指定します。
-anchor	リンクは、目次への完全修飾参照によって指定されます。以下はその一例です。 <toc link_to="../the_other_plugin_id/path/to/toc.xml#anchor_id"/>
-notree	org.eclipse.help.toc コントリビューションは、対象とするヘルプの構造と、その構造に他のプラグインが寄与するヘルプを統合した構造とを含む関連 XML ファイルを 1 つ以上指定します。 プロジェクト全体のマニュアルを作成する場合は、複数の TOC XML ファイルが作成されるように指定してください。 注: このフラグ・パラメーターがない場合、作成される TOC XML ファイルは 1 つだけとなります。

7. ドックレットは 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 ファイル
8. コマンド・プロンプト (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)。

                javadoc @config @options @packages

                -doclet com.ibm.malup.doclet.config.TOCDoclet -docletpath C:\doclet\bin\TOCNavDoclet.jar

                -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

                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 ファイル

                <?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)。

                # 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)。

                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 に記載するような内容が含まれます。

                <?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)。

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

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

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

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)。

                 <?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)。

                 <?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) とでは、マニュアルを表示したときに何の違いもありません。

                 <?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) を実行します。

                 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 属性と一致することに注意してください)。

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

上に戻る

マニュアルを表示する

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

上に戻る

注意事項

「簡潔さこそが効率性の命である」- Austin Freeman の言葉 コメントを書くという良い習慣は、作成されたコードの品質にとっても、そのコードを使用する最終的な製品の品質にとっても非常に重要です。

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

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

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

上に戻る

まとめ

Java API リファレンスのソースはプログラマーが所有し、プログラマーとテクニカル・ライターの双方によって編集されます。

この記事で紹介した 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 関連のアプリケーションを最大限活用できるように開発者を支援する記事、チュートリアル、そしてヒントが文字通り数百と紹介されていますが、新しいトピックで独自の方法を見つけたいという読者にとっても興味深い情報となるはずです。
  • IBM alphaWorks の Documentation Enhancer for Java は、対応する Java クラスファイルの静的分析により収集した新しい情報 (セマンティック情報、ソート、ナビゲーション機能) を追加して、Javadoc ファイルを拡張するツールです。
  • IBM developerWorks の「Eclipseのヘルプ・システムを使ってプロジェクトを文書化する」を参照してください。
  • Java 言語では、Javadoc コメント規約による API ドキュメントへの統合アプローチを採用しています。David Gallardo の記事「Java の理論と実践: それをドキュメント化しなければならないか」を読んで、プラグイン開発環境のコード生成ウィザードで Eclipse プラグインを作成する方法を学んでください。
  
  
• Eclipse プラットフォームに関する資料を他にも調べてください。Eclipse はオープン・ソース・コミュニティーで、そのプロジェクトはソフトウェア作成用の拡張可能な開発プラットフォームとアプリケーション・フレームワークを提供することに重点を置いています。
  • Javadoc 生成ウィザードでは Javadoc generation を生成することができます。このウィザードは javadoc.exe ツールのユーザー・インターフェースで、Java JDK に用意されています。
  
  
• DITA Open Toolkit は、OASIS DITA Technical Committee による DITA (Darwin Information Typing Architecture) DTD およびスキーマに関する仕様の実装です。このツールキットは DITA コンテンツ (マップとトピック) を配布可能な形式に変換します。
  • 「DITA XML Specialization for Writing Language-conformant Reference Documentation for API libraries」の詳細を調べてください。
  • Java クラス・ライブラリーのドキュメント化のベースとなる「Java API Reference Specialization」の詳細を調べてください。
  
  
• この連載「Javadoc API リファレンス・マニュアル」の第 1 回目の記事
  • 「Eclipse ヘルプに Java API リファレンス・マニュアルを編成する方法」
  
  

• DITA API Specialization (javaapiref0.8.zip) は、汎用 API リファレンス仕様を拡張する方法の一例として使用、または検討できます。
  
  

• 著者の連載「API documentation process series」では、以下の記事に開発者とライターとのコラボレーションに関する詳しい説明が記載されています。
  • 「Creating Javadoc API documentation with directly updated source」
  • 「Creating Javadoc API documentation with indirectly updated source」
  
  

著者について

		Mariana Alupului は、IBM Software Group、Rational Software のシニア・テクニカル・ライター (API) です。ソフトウェア・プログラミング環境でのJava、VB、C++ 対応 API ドキュメンテーション・プロジェクトのリーダーを務める傍ら、IBM Corporation のメンバーとして、言語に適合したAPI ライブラリーのリファレンス・マニュアルを作成するための DITA (Darwin Information Typing Architecture) XML 特殊化機能を開発しています。API リファレンス形式のガイドラインの作成にも協力している彼女は、統合 ID-Support Council および ID Technical Writers Councilのメンバーでもあります。また、2005年の「Beyond the Bleeding Edge」セッションには Society for Technical Communication のメンバーとして出席しました。

記事の評価

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

この記事を共有する はてなブックマーク livedoorクリップ del.icio.us Buzzurl（バザール） Choix！ Saafブックマーク FC2ブックマーク MM/memo ニフティクリップ Yahoo!ブックマーク CZブックマーク newsing

上に戻る