目次


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

第 3 回 JavaTOC ドックレットと ANT を実行して生成する Eclipse Javadoc API リファレンス構造

Comments

コンテンツシリーズ

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

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

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

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

これまでの要約

連載の第 1 回「Eclipse ヘルプにJava API リファレンス・マニュアルを編成する方法」では、使いやすくて検索ができる Java アプリケーション・プログラミング・インターフェース (API) のリファレンス・マニュアルを作成する方法を紹介しました。その記事で紹介した方法は、Javadoc による標準的なソリューションによるものと、私が開発した JavaTOC ドックレットを使って作成した Eclipse プラグイン・ヘルプ・システムを使う方法です。

連載の第 2 回「JavaTOC ドックレットを使って生成する Eclipse Javadoc API リファレンス構造」では、JavaTOC ドックレット (今回のダウンロードに含めてあります) と、そのコマンド・プロンプトでの使い方を紹介しました。さらに、JavaTOC ドックレットを使って Javadoc API リファレンス・マニュアルの XML TOC ナビゲーションを生成し、検索機能を改善する手順を説明しました。

JavaTOC ドックレットを使って作成する Eclipse プラグイン (Javadoc API リファレンス・マニュアル)

Eclipse プラットフォームのヘルプ・システムでは、org.eclipse.help.contributions 拡張ポイントを使って自ら作成したプラグインをオンライン・ヘルプに追加することができます。この場合、オンライン・ヘルプをコード・プラグインの一部に加えることも、固有の文書プラグインとして別途提供することもできます。独自の文書プラグインがあると、ソース・コードのコピー上で作業できるため、リファレンス生成プロセスを開発プロセスから切り離せるという利点があります。また、開発チームと文書化チームが別々のグループであったり、文書化のソースとソース・コード間の依存関係を減らしたいという場合には、この方法を検討してみると役に立つかもしれません。

org.eclipse.help.contributions 拡張ポイントには、ヘルプを拡張するために使用できる 4 つの要素、topics、infoset (ブック)、infoview、actions (関連付け) があります。infoset および actions コントリビューションは、コントリビューションの詳細が含まれる関連 .xml ファイルを指定します。

設計上の制約

JavaTOC ドックレットを実行して TOC XML ナビゲーション・ファイルと Javadoc の両方を生成することも、あるいは JavaTOC ドックレットを実行して TOC XML ナビゲーション・ファイルだけを生成し、Javadoc は開発者が作成したものを使うこともできます。この記事で紹介するソリューションでは、Eclipse 開発環境で 標準 Javadoc Generation ウィザードを使って Java API リファレンス・マニュアルの Javadoc を作成し、JavaTOC ドックレットを使って TOC XML ナビゲーション・ファイルを生成します。

Eclipse 内での JavaTOC ドックレットの実行方法についての説明では、最初にカスタム・ドックレット・ウィザード、次に Ant ビルド・システムを使用します。Ant で作業した経験がない方は、Jakarta Web サイトまたは「Open Source Java: Ant」を参照してください。

ワークフロー

まず、JavaTOC プラグイン・ビルド・ツール (JavaAPITools) をワークスペースに追加してください。

  • お使いの Eclipse のバージョンで使用しているワークスペース・ディレクトリーを見つけます。このディレクトリーは通常、Eclipse がインストールされたディレクトリー内の「workspace」という名前のサブディレクトリーです。ショートカットまたはスクリプトを使用して Eclipse を起動している場合には、そのショートカットまたはスクリプトの現行作業ディレクトリーの下にある「workspace」サブディレクトリーとなります。
  • パッケージ (JavaAPITools) をダウンロードしてワークスペースに解凍します。これにより、「JavaAPITools」プロジェクトが作成されます。
  • JavaAPITools」プロジェクトと作業対象の Java プロジェクトを Eclipse ワークスペースにインポートします。

既存の Java プロジェクトをワークスペースにインポートするには、Import Wizard を使用してください。この記事でのサンプル用に「org.dita.dost」という Java プロジェクトを新規に作成し、DITA のコンテンツ (マップおよびトピック) を配布可能なフォーマットに変換する DITA Open Toolkit のソース・コード (src フォルダー) を追加しておきました。このプラグインは「ダウンロード」セクションからダウンロードできます。

Eclipse Javadoc Generation ウィザード (標準ドックレット) を使って Javadoc 文書を作成する方法

  • Eclipse 開発環境で標準 Javadoc ドックレットを使って Javadoc 文書を作成する方法は、以下のとおりです。
  • Eclipse の左ペインで、Javadoc 文書を作成する対象のソース・コード・プラグインを選択します。
  • 選択したプラグインを右クリックし、ドロップダウン・リストから Export を選択します。Export ウィンドウが開きます。
  • Javadoc を選択してから Next をクリックします。Generate Javadoc ウィンドウが開きます。
  • Generate Javadoc ウィンドウで、JAR ファイルにエクスポートするパッケージを選択します。このリストは、ワークベンチを選択すると初期化されます。Javadoc ツールの実行中は一度に 1 つのプロジェクトのクラスパスしか使えないので、複数のプロジェクトを同時に選択することはできません (図 1)。
  • メンバーの可視性を選択します (通常は PackagePublic)。
  • Use Standard Doclet を選択して標準ドックレット (デフォルト) により Javadoc コマンドを起動します。
  • Destination: 標準ドックレットが生成した文書を書き込む宛先を選択します。この宛先はドックレット固有の引数なので、カスタム・ドックレットの使用時には有効になりません。
    • 標準ドックレットが書き込む宛先は、例えば「doc.dita.dost.doc\topics」に設定することができます (図 2)。
図 1. Javadoc Generation ウィザード (標準ドックレット)
Javadoc Generation ウィザード (標準ドックレット)
Javadoc Generation ウィザード (標準ドックレット)
図 2. 宛先
宛先
Javadoc Generation ウィザードが提供するサポート・オプション表
オプション説明
Document title文書のタイトルを指定します。
Generate use page文書に Use ページを含める場合には、このオプションを選択します。
Generate hierarchy tree文書に Tree ページを含める場合には、このオプションを選択します。
Generate navigator bar文書にナビゲーター・バー (ヘッダーとフッター) を含める場合には、このオプションを選択します。
Generate index文書に Index ページを含める場合には、このオプションを選択します。
Generate index per letter文字ごとに索引を生成します。このオプションは、Generate Index が選択されると有効になります。
@author@author タグを文書化する場合には、このオプションを選択します。
@version@version タグを文書化する場合には、このオプションを選択します。
@deprecated@deprecated タグを文書化する場合には、このオプションを選択します。
deprecated list文書に Deprecated ページを含める場合には、このオプションを選択します。このオプションは、@deprecated オプションが選択されると有効になります。
Select referenced classes to which Javadoc should create linksJavadoc 以外による文書が参照される場合、Javadoc に作成するリンク先の文書を指定します。
  • Select All: 他のすべての文書へのリンクを作成します。
  • Clear All: 他の文書へのリンクは作成しません。
  • Configure: 参照先の JAR またはプロジェクトの Javadoc のロケーションを設定します。
Style sheet使用するスタイル・シートを選択します。
  • Finish をクリックして Javadoc 文書を作成するか、または Next をクリックして Javadoc 文書の生成オプションを追加で指定します。

: 詳細は、Eclipse Help Platform の Javadoc generation を参照してください。

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

  • ドックレットは、現在のプラグイン文書ディレクトリーである org.dita.dost\org.dita.dost.doc\topics\ にプラグイン文書の出力 HTML ファイルを生成します。

Eclipse Javadoc Generation ウィザードと JavaTOC ドックレット (カスタム・ドックレット) を使って TOC XML ナビゲーション・ファイルおよび Javadoc プラグイン・ファイルを作成する方法

Eclipse 開発環境で、カスタマイズした JavaTOC ドックレットを Javadoc と組み合わせて使用する場合の手順は以下のとおりです。

  • Eclipse の左ペインで、Javadoc 文書を作成するソース・コード・プラグインを選択します。
  • 選択したプラグインを右クリックし、ドロップダウン・リストから Export を選択します。Export ウィンドウが開きます。
  • Javadoc を選択してから Next をクリックします。Generate Javadoc ウィンドウが開きます。
  • Generate Javadoc ウィンドウで、JAR ファイルにエクスポートするパッケージを選択します。このリストは、ワークベンチを選択すると初期化されます。Javadoc ツールの実行中は一度に 1 つのプロジェクトのクラスパスしか使えないので、複数のプロジェクトを同時に選択することはできません。
  • メンバーの可視性を選択します (通常は PackagePublic)。
  • Use Custom Doclet を選択し、ドックレットの修飾型名(com.ibm.malup.doclet.config.DITADoclet) を Doclet name に追加します 。Doclet class path にはドックレット・クラスに必要なクラスパス(<eclipse_workspace>\JavaAPITools\bin\JavaTOC.jar) を追加します 。
    注: <eclipse_workspace> は、Eclipse ワークスペースの絶対パス (C:\eclipse\workspace) です。
    • Destination: 標準ドックレットが生成した文書を書き込む宛先を選択します。この宛先はドックレット固有の引数なので、カスタム・ドックレットの使用時には有効になりません。
      標準ドックレットが書き込む宛先は、例えば「doc.dita.dost.doc\topics」に設定することができます。
  • Next をクリックします。
図 3. Javadoc Generation ウィザード (カスタム・ドックレット)
Javadoc Generation ウィザード (カスタム・ドックレット)
Javadoc Generation ウィザード (カスタム・ドックレット)
図 4. 宛先
宛先

追加の Javadoc オプション

  • Extra Javadoc options (path names with white spaces must be enclosed in quotes) (追加の Javadoc オプション (パス名に空白が含まれる場合はパス名を引用符で囲んでください)) に、リスト 1 の内容を追加してください。この内容は、サンプル org.dita.dost プラグインの場合です。
    1. -d <destination_directory> には、生成された文書の宛先ディレクトリーを指定します。デフォルトでは、現行ディレクトリー ("." というパス名で指定されたディレクトリー) が設定されます。
    2. -pluginid <plugin_id> には、Eclipse プラグインの id ページの id を含めます。
    3. -doctitle <html_code> には、Eclipse プラグインの名前ページのタイトルを含めます。
    4. -overview <file> には、Eclipse プラグインの概要ページのファイルを指定します。
    5. -version <plugin_version> には、プラグイン・バージョン id の詳細を指定します。
    6. -provider <plugin_provider> には、プラグイン・プロバイダー名の詳細を指定します。
    7. anchor <file> には、目次への完全修飾参照によってリンクを指定します。以下はその一例です。「../the_other_plugin_id/path/to/toc.xml#anchor_id」
    8. -notree には、大規模なプロジェクトのマニュアルを作成する場合、複数の XML TOC ファイルが作成されるように指定します。
リスト 1. 追加の Javadoc オプション
-d C:\eclipse\workspace\org.dita.dost\org.dita.dost.doc\
-pluginid org.dita.dost.doc
-doctitle 'Building DITA output' 
-version '7.0.0.1' 
-provider 'IBM' -subsystemtoc

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

  • ドックレットは、現在のプラグイン・ディレクトリーである org.dita.dost\org.dita.dost.doc\ フォルダーに、プラグインの出力 TOC XML ファイルの他、いくつかの有用なファイルを生成します。JavaTOC ドックレットによって生成されるファイルは以下のとおりです。
    • plugin.xml
    • plugin.properties
    • build.properties
    • .project
    • META-INF\MANIFEST.MF
    • primary.plugin.toc.xml
    • org.dita.dost.xxx.toc.xml ― ヘルプ・ブラウザーにナビゲーション・ツリーをビルドするための TOC XML ファイル
  • プラグインの nameidversion、および provider-name の値は、d-doctitle-version、および -provider プロパティーから自動生成されます。
  • プラグインのマニフェスト・ファイルはストリングをキー (%pluginName など) に置き換えて外部化し、plugin.properties ファイルに Plugin.name = Online Help Sample Plugin という形のエントリーを作成します。

JavaAPITools (build.xml & JavaTOC ドックレット) と Ant を使って文書プラグインを作成する方法

JavaAPITools の主な目的は、公開用 API リファレンス・マニュアルの Javadoc を備えた NEW DOCUMENTATION プラグインを作成し、この Java API リファレンス・マニュアルを Javadoc 用の TOC XML ナビゲーション・ファイルも含めた形で Eclipse ヘルプ・システムに統合するために必要な、すべての Eclipse プラグイン・ファイルを作成することです。

プラグイン・ビルド・ツール (buildAPITools) をインストールする

JavaAPITools パッケージには、Eclipse 文書プラグインを作成するための Eclipse ビルド・スクリプトが用意されています。このスクリプトにより、Eclipse 内で Java プロジェクト・プラグインを変換し、Eclipse ターゲット・ランタイムを使ってプラグインをテストすることができます。Javadoc 文書を生成するには、プラグインのなかに build.xml という名前の ANT スクリプトを作成します。この ANT スクリプトに必要な JavaAPITools build.xml ビルド・ツールは、開発システム (ワークスペース) のいずれかの場所に置かれていなければなりません。さらに、このスクリプトによって、最終的な xxx.doc プラグインがデプロイメント用にどのようにパッケージ化されるかも決定できなければなりません。

  • パッケージをダウンロードし、ワークスペースに「JavaAPITools」プロジェクトを作成して、このプロジェクトにパッケージを解凍します。
  • 作業対象のプラグインを Eclipse ワークスペースにインポートします。この記事でのサンプル用に Java プロジェクトを新規に作成し、DITA のコンテンツ (マップおよびトピック) を配布可能なフォーマットに変換する DITA Open Toolkit のソース・コードをディレクトリーごと src フォルダーとして追加しておきました。このプラグインは「ダウンロード」セクションからダウンロードすることができます。あるいは、サンプル・プロジェクト上で実行しても構いません。

プラグインのデプロイメント用パッケージ化を行う

Eclipse 3.2 より前のバージョンでは、HTML ファイルと併せて、生成した Javadoc 文書を doc.zip ファイルとして保持することになりますが、Eclipse 3.2 以降では文書プラグイン全体を 1 つの jar ファイルとして装備することができます。この jar ファイルには、doc.zip ファイルに圧縮してあるすべてのファイルと、Eclipse プラグイン・ファイル (manifest.mf、plugin.xml、plugin.properties など) が含まれます。

Eclipse 3.1 以降、プラグインは (1 つ以上の jar ファイルを含む) 複数のファイルが含まれるディレクトリーとしてデプロイすることも、単一の jar ファイルとしてデプロイすることもできます。

リスト 2. build.properties
bin.includes = META-INF/,\
               .project,\
               plugin.xml,\
               toc.xml,\
               plugin.properties,\
               doc.zip,\
               bin/

コメント: 元のプラグインをディレクトリーとしてデプロイする場合は、build.properties ファイルに doc.zip ファイルが含まれている必要があります。一方、プラグインを単一の .jar としてデプロイする場合には、build.properties に doc.zip が含まれていてはいけません。代わりに、droot ディレクトリーと doc.zip ファイル内に作成されていたはずのファイルを含めます。

さらに、このような文書プラグインを含む .doc-feature プラグインでは、該当するプラグインの feature.xml ファイルに unpack="false" 属性が設定されている必要があります。

ANT ビルド・ファイルを作成、管理、実行する

  • builAPIToolsbuild.xml を右クリックして Run As > External Tools を選択します。Builders セクションで New Lunch Configuration .. を選択し、新しい Ant ビルド構成を作成します。
  • 表示された構成ダイアログで、名前を固有のもの (例えば、Build Plugin Documentation) に設定します。起動構成の Main タブでワークスペースをブラウズして、JavaAPITools の build.xml ファイルを選択します。Base directory に値 ${project_loc} を追加します。

以下の図 5 は、Ant 起動構成ダイアログの Main タブです。

図 5. ANT ビルド・ファイルを実行するための設定
ANT ビルド・ファイルを実行するための設定
ANT ビルド・ファイルを実行するための設定
  • Arguments:
    • -verbose 引数により、機能していない特定のコマンドに関する情報を追跡することができます。‐quiet 引数は、ビルド・ファイルのエコー・タスクによって生成された以外のほとんどのメッセージを抑止し、-debug は Eclipse Console にデバッグ情報を出力します。
    • ‐Dbuild.toc.tree=true 引数は -build.toc.tree プロパティーをオーバーライドし、値を true に設定してからビルド・スクリプトが実行されるようにします。これにより、TOC XML ファイル (xxx.toc.xml) は複数ではなく、主要なものが 1 つだけ生成されることになります。

build.xml ANT ファイルを作成する

build.xml スクリプトは関連するコンポーネント・プラグインの Javadoc 文書を作成するために必要なすべての情報を定義し、doc.zip ファイルを作成するか、あるいは生成されたファイルをプラグインのルートにコピーします。このファイルのなかで使うことができるタスクについての詳細は、JavaAPITools/build.xml を参照してください。

このファイルの初期コンテンツは以下のようになっているはずです。

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

<!-- **************************************************************  -->
<!-- ANT build file for Eclipse toc files and documentations plugins -->
<!-- Mariana Alupului 10/08/2006                                     -->
<!-- **************************************************************  -->

<project name="build" default="main">
	<echo message="${ant.project.name}: ${ant.file}"/>
	
	
<!-- **************************************************************************** The main build target. **************************************************************************** --> <target name="main" depends="setup, useManifestMF, usePluginXML, badPlugin, runJavaDoc, runJavaTOCDoclet, deployPlugin, copyPlugin, cleanProject" description="Build Plug-in Documentation"> <echo message="${ant.project.name}: ${ant.file}"/> </target>
Comment: The "main" target executes the targets in the depends attribute in the order they appear (from left to right). Keep in mind that it is possible that a target can get executed earlier when an earlier target depends on it: (setup, useManifestMF, usePluginXML, badplugin, runJavaDoc, runJavaTOCDoclet, generateZip, copyPlugin, cleanProject).

<target name="init" description="Project variables"> <property name="ECLIPSE_HOME" value="../../"/> <property name="build.plugin" value="jar"/> <property name="project.dir" value="${basedir}" /> <property name="build.toc.tree" value="false" /> </target> <target name="setup" depends="init" description="Setup the Project"> <tstamp> <format property="now" pattern="d MMMM yyyy HH:mm:ss aa" /> </tstamp> <echo>=== Starting Building Plugin Documentation ===</echo> <echo>=== ${now} ===</echo> </target> Comment:
Ant buildfile provides access to all system properties as if they had been defined using a <property> task.

<target name="validatePlugin" description="Select plugin.xml or manifest.mf"> <condition property="plugin.xml.exists"> <available file="${project.dir}\plugin.xml" /> </condition> <condition property="manifest.mf.exists"> <available file="${project.dir}\META-INF/MANIFEST.MF" /> </condition> <condition property="invalid.plugin"> <and> <not> <isset property="plugin.xml.exists" /> </not> <not> <isset property="manifest.mf.exists" /> </not> </and> </condition> </target> <target name="useManifestMF" depends="validatePlugin" if="manifest.mf.exists" description="Get plugin name from MANIFEST.MF "> <loadproperties srcFile="${project.dir}\META-INF/MANIFEST.MF"> <filterchain> <linecontains> <contains value="singleton" /> </linecontains> <replacestring from=";" to=".doc" /> <replacestring from=" " to="" /> <replacestring from="singleton:=true" to="" /> </filterchain> </loadproperties> <property name="plugin.name" value="${Bundle-SymbolicName}" /> <loadproperties srcFile="${project.dir}\META-INF/MANIFEST.MF"/> <property name="bundle.name" value="${Bundle-Name}" /> <property name="version.name" value="${Bundle-Version}" /> <property name="vendor.name" value="${Bundle-Vendor}" /> </target> <target name="usePluginXML" depends="validatePlugin" if="plugin.xml.exists" unless="manifest.mf.exists" description="Get plugin name from plugin.xml if MANIFEST.MF does not exist "> <xmlproperty file="${project.dir}\plugin.xml" /> <property name="plugin.name" value="${plugin(id)}.doc" /> <property name="bundle.name" value="${plugin(bundle-name)}" /> <property name="version.name" value="${plugin(bundle-version)}" /> <property name="vendor.name" value="${plugin(bundle-vendor)}" /> </target> <target name="badPlugin" depends="validatePlugin" if="invalid.plugin" description="Processing ends if plugin is invalid "> <fail message="ERROR::Plugin ${project.dir} is invalid. No plugin.xml was found." /> </target> Comment: The Ant buildfile provides access to the MANIFEST.MF file or/and to the plugin.xml file, and uses the existing plug-in name, id, version name and vendor name from the existing Java plugin.
An Error appears in your console if no plugin.xml or MANIFEST.MF was found.

<target name="runJavaDoc" depends="validatePlugin" unless="invalid.plugin" description="Generate JavaDoc API documentations"> <mkdir dir="${plugin.name}" /> <mkdir dir="${plugin.name}/META-INF" /> <echo>SUCCESS: Create directory ${basedir}\${plugin.name}</echo> <javadoc access="public" author="true" destdir="${plugin.name}\topics" nodeprecated="false" nodeprecatedlist="false" noindex="false" nonavbar="false" notree="false" packagenames="*" source="1.4" sourcepath="src" splitindex="true" use="true" version="true"/> </target> Comment: See Table of supported options provided by Javadoc Generation wizard if you want to add more options to run the standard Javadoc.

Example: To add the Author name (@author ) to the documentation, add author="true" .

<target name="runJavaTOCDoclet" unless="invalid.plugin" description="Generate Eclipse XML TOC files"> <property name="buildAPITools" value="../JavaAPITools/bin/JavaTOC.jar" /> <echo>End Phase I Standard Doclet - Start Phase II JavaTocDoclet...</echo> <!-- <loadproperties srcFile="${project.dir}\plugin.properties"/> <property name="plugin.link" value="${Plugin.link_to}" /> --> <javadoc access="public" classpath="." sourcepath="src" notree="${build.toc.tree}" packagenames="*" > <doclet name="com.ibm.malup.doclet.config.TOCDoclet" path="${buildAPITools}"> <param name="-d" value="${basedir}\${plugin.name}"/> <param name="-plugintitle" value="API Reference (${bundle.name})"/> <param name="-pluginid" value="${plugin.name}"/> <param name="-version" value="${version.name}"/> <param name="-provider" value="${vendor.name}"/> <!-- <param name="-anchor" value="${plugin.link}"/> --> </doclet> </javadoc> </target> Comment: See Listing 1. Extra Javadoc options if you want to add more options to run the JavaTOC doclet tool.

Example: —overview <file> <param name="-overview" value="${basedir}\${plugin.name}\overview.html"/>

Example: —anchor <file> <param name="-anchor" value="../the_other_plugin_id/path/to/toc.xml#anchor_id"/> <target name="deployPlugin" description="If plug-in is packaged as a directory (unpacked)"> <loadfile srcFile="${basedir}/build.properties" property="build_properties" /> <condition property="deployPlugin" > <contains string="${build_properties}" substring="doc.zip"/> </condition> <antcall target="createDocZip" /> </target> <target name="createDocZip" if="deployPlugin" description="The plug-in is packaged as a directory"> <echo>== The .doc plug-in is to be deployed as a directory ==</echo> <zip destfile="${project.dir}\${plugin.name}/doc.zip" basedir="${plugin.name}"> <include name="topics/**" /> <include name="images/**" /> <include name="pdf/**" /> <include name="*.css" /> </zip> <delete dir="${project.dir}\${plugin.name}/topics" /> </target> Comment: The Ant buildfile provides access to the build.properties file (if the plugin is to be deployed as a directory, or as a jar file) and creates the doc.zip file.

<target name="copyPlugin" description="Copy the project to workspace"> <copy includeemptydirs="true" todir="${ECLIPSE_HOME}/workspace/${plugin.name}"> <fileset dir="${plugin.name}" excludes="**/*.launch, **/buildJavaDoc.bat"/> </copy> </target> <target name="cleanProject" description="Cleans the project"> <delete dir="${project.dir}\${plugin.name}" /> <delete dir="../buildAPITools/${plugin.name}" /> <echo>=== End Building ${plugin.name} Plug-in Documentation ===</echo> <echo>=== ${now} ===</echo> </target> Comment: Copy the project to your workspace.

</project>

プラグインの自動ビルドを実行する

  • プラグイン・プロジェクトを選択します。
  • Run > External Tools > External Tools > Build Plugin Documentation の順にクリックします。
    • ビルドが実行され、Console ビューに実行状況およびエラーが表示されます。
    • コンソールに「BUILD FAILED」エラーが表示された場合は、コンソール・メッセージの最後に「BUILD SUCCESSFUL」と表示されるまで、発生した問題を確認、修正してからビルドをやり直します。
    • 文書プラグインのビルドが (開発環境内で) 正常に完了すると (ANT エラーが出なくなった状態)、HTML ファイル用の \topics フォルダーが作成され、ルート・ディレクトリー内には doc.zip ファイルとプラグイン・マニフェスト・ファイルが含まれているはずです。
    • ビルド・プロパティーには toc*.xml ファイル、plugin.properties、META-INF、そして .project ファイルがすべて含まれます。doc.zip ファイルを作成した場合、build.properties ファイルには doc.zip も含まれることになります (変更しないでください)。プラグインを単一の jar ファイルとしてデプロイする予定であれば、build.properties ファイルには doc.zip ファイルではなく、作成された最上位レベルのディレクトリー (topics) を含める必要があります。

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

  • このサンプル (org.dita.dost.doc plug-in) の場合、ANT ビルド・ファイルは現在のプラグイン・ディレクトリーである workspace\org.dita.dost.doc ディレクトリーにプラグインの出力 XML ファイルとその他複数の有用なファイルを生成します。
  • build.toc.tree の値が false の場合と true の場合とでは、ANT ビルド・ファイルが生成する出力ファイルは以下のように異なります。
    <property name="build.toc.tree" value="false" /><property name="build.toc.tree" value="true" />
    • .project
    • plugin.xml
    • plugin.properties
    • META-INF\MANIFEST.MF
    • topics\ ― すべての HTML ファイル
    • doc.zip
    • primary.plugin.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.bat ― JavaDoc ツールを実行するための BAT ファイル
    • .project
    • plugin.xml
    • plugin.properties
    • META-INF\MANIFEST.MF
    • topics\ ― すべての HTML ファイル
    • doc.zip
    • org.dita.dost.doc.toc.xml ― ヘルプ・ブラウザーにナビゲーション・ツリーをビルドするための主要な TOC XML ファイル
    • buildJavaDoc.bat ― JavaDoc ツールを実行するための BAT ファイル
  • ANT ビルド・ファイルを以下のように変更すると、さらに機能を追加することができます。
    • Java プロジェクトの plugin.properties に、Plugin.notree = false を追加します。
      Plugin.name = DITA Dost 
      Plugin.providerName = I.B.M.
      Plugin.link_to = ../com.ibm.xde.mda.doc/primary.plugin.toc.xml#api
      Plugin.anchor_id = api
      Plugin.notree = false
    • build.xml に、以下の内容を追加します。

      <loadproperties srcFile="${project.dir}\plugin.properties"/>
               		<property name="plugin.link" value="${Plugin.link_to}" />

プラグインをワークスペースにインポートする

文書プラグインをワークスペースにインポートするには、Import ウィザードを使用することができます。

  • メイン・メニュー・バーで File > Import... を選択します。Import ウィザードのウィンドウが開きます。
  • General > Existing Project into Workspace を選択してから Next をクリックします。
  • ルート・ディレクトリーを選択し、Browse をクリックしてワークスペースのディレクトリーを指定します。
  • Projects の下から、インポートする org.dita.dost.doc プロジェクトを選択します。
  • Finish をクリックしてインポートを開始します。
図 6. ワークスペースへのプラグインのインポート 1
ワークスペースへのプラグインのインポート 1
ワークスペースへのプラグインのインポート 1
図 7. ワークスペースへのプラグインのインポート 2
ワークスペースへのプラグインのインポート 2
図 8. ワークスペースへのプラグインのインポート 3
ワークスペースへのプラグインのインポート 3
ワークスペースへのプラグインのインポート 3

Java API リファレンス・プラグインのテスト

  • 以下の手順に従ってターゲット・ランタイム環境をセットアップします。
    • Window > Preferences > Plug-in Development > Target Platform の順に選択します。
    • Location を、外部にインストールした製品のメイン eclipse ディレクトリーに設定します。Eclipse ディレクトリーにプラグインのリストが表示されます (表示されるまで暫く時間がかかります)。
    • OK をクリックして Target Platform の設定を保存します。
  • Plugin Development パースペクティブで、Run > Run を選択して実行構成を作成します。この操作によって、実行構成を行うページが表示されます。
    • Eclipse Application 構成をクリックしてから New ボタンをクリックし、この構成をテスト用 JavaTOCdoclet Eclipse プラグインとして識別する名前を指定します。ここでは Test Plugin Doc という名前にします。
    • Main タブのロケーション・フィールドでワークスペースのディレクトリーを選択します。ターゲット・ランタイムの使用中に実行した内容は、.metadata フォルダーの .log ファイルを含め、このワークスペースに書き込まれます。
    • Program to Run から Run a product を選択し、org.eclipse.platform.ide を指定します。
    • Plug-ins タブで、Choose plug-ins and fragments to launch from the list を選択します。
    • Workspace Plug-ins からテスト対象のプラグインを選択します。プラグインが新しいもので、ターゲット・ランタイムと一緒にインストールされていないとしても、このオプションによってローカル・プラグインのテストが可能になります。
    • External Plug-ins リストは変更しないままにします。
    • Add new workspace plug-ins to this launch configuration automatically チェック・ボックスにチェック・マークを付けます。
    • Apply をクリックして変更内容を保存します。
    • Plug-in Development パースペクティブに切り替えて、Run > Run の順にクリックします。
      • 作成した実行構成 (Test Plugin Doc) を選択して Run をクリックします。すると、ターゲット・ランタイムが起動します。つまり、外部の製品が起動するということですが、起動にはローカル・プラグインのコピーが使用され、その製品でのバージョンは使用されません。
      • : プラグインを実行すると Run History に実行構成 (Test Plugin Doc) が表示されるので、Run > Run History > Test Plugin Doc を選択するか、あるいはツールバー・アイコンを使うかしてターゲット・ランタイムを起動することができます。Run
      • Run Build Plugin Docs
      • デフォルトでは、ターゲット・プラットフォームにあるすべてのプラグインだけでなく、ワークスペース内のすべてのオープン・プラグイン・プロジェクトが起動されます。このデフォルトを含め、すべてデフォルト設定のままで差し支えありません。

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

新しい Eclipse テスト・プラットフォームで Help > Help Contents の順に選択すると、作成したプラグインが追加されたヘルプ・ウィンドウが表示されます (図 9 のような画面)。

図 9. Help ― Eclipse SDK
Help ― Eclipse SDK
Help ― Eclipse SDK

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

以上の作業が終わったら、あとは Workbench User Guide で説明している Export wizard を使ってすべてを 1 つの構造にパッケージ化するだけです。このウィザードでは、Eclipse ワークベンチからリソースをエクスポートできます。

注意事項

  • この記事に記載した情報はテクニカル・ライターとしての私の意見と手法であり、公式な IBM テストを受ける前の「現状のまま」の状態です。そのため、明示または黙示を問わず一切の保証はありません。
  • JavaTOC ドックレット・ツールは著者の Mariana Alupului が開発した公開済みのツールです。このツールは IBM の知的財産の一部であり、www.ip.com で公開されています。
  • この情報の使用、またはこの記事に記載した手法の実装については、読者の責任であり、読者の評価能力および動作環境への統合能力に依存します。

まとめ

この記事で紹介した JavaTOC ドックレットを使うと、HTML と少数の追加文書要素をベースにヘルプ・マニュアルを作成することができます。このドックレットでは、Eclipse プラットフォーム文書を作成し、さらにその文書を使って既存の Eclipse ヘルプ・システムの XML および HTML 出力形式を作成することもわけありません。

今回の記事では、ソース・コードを文書化する方法ではなく、JavaTOC ドックレットを使って Eclipse プラットフォーム文書を開発する方法を説明しました。作成される文書は専門家向けなので、最も重要な仕事は自分で行わなければなりません。つまり、開発者のソース・コードを完全に文書化して完全な Java API リファレンス・マニュアルにするという仕事です。この無料のオープンソースによるソリューションなら、文書開発プロセスを単純化し、ドックレットを操作するだけで自動的にプラグイン構造、TOC ナビゲーション、そして HTML ファイルを作成することが可能になります。

developerWorks の XML ゾーンに掲載予定の記事では、Eclipse プラグイン・ヘルプ・システム用の DITAdoclet ツールを使って、検索可能な Java API リファレンス・マニュアル (TOC ナビゲーション) を自動的に生成するプロセスについて取り上げます。この「How Java API Documentation is organized in DITA API specialization」にはダウンロード用の DITAdoclet ツールを用意し、このツールで DITA API ファイルと Java ソース・コードの XHTML 出力を生成する方法を説明する予定です。 また、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 Platform で他にも資料を探してください。Eclipse は、ソフトウェアをビルドするための拡張可能な開発プラットフォームとアプリケーション・フレームワークを重点としたプロジェクトを手掛けるオープンソース・コミュニティーです。
    • Javadoc generation ウィザードでは Javadoc 文書を作成することができます。このウィザードは 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 リファレンス仕様の拡張例として使用、または検討できます。

コメント

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

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