Quick Review

In Part 1 of this series, How Java API reference documentation is organized in Eclipse Help the article introduces different approaches for generating easy-to-use and searchable Java application programming interfaces (API) reference documentation. The approaches described in the article are the Javadoc standard solution and the Eclipse Plug-in Help System generated using the JavaTOC doclet that I developed.

In Part 2 of this series, Eclipse Javadoc API reference structure generated using the JavaTOC doclet the article presents the JavaTOC doclet (inclusive download) and how to use it using Command Prompt. It shows how JavaTOC doclet generates the XML TOC navigation and the improved search capability for the Javadoc API reference documentation.

Generate Eclipse plug-in (Javadoc API reference documentation) using JavaTOC doclet

The Eclipse platform Help system allows you to contribute your plug-ins to the online Help using the org.eclipse.help.contributions extension point. You can either contribute the online Help as part of your code plug-in or provide it separately in its own documentation plug-in. Having your own documentation plug-in provides the benefit of working on a copy of the source code and the references generation process being separate from the development process. It might be beneficial to consider this approach in those situations where the development and the documentation team are different groups, or where you want to reduce the dependency between the documentation source and the source code.

The org.eclipse.help.contributions extension point provides four elements through which you can contribute your help: topics infoset (book) infoview actions (wiring). The infoset and actions contributions specify an associated .xml file that contains the details of the contribution.

Design Constraints

You can run the JavaTOC doclet to generate the TOC XML navigation files and the Javadoc, or run the tool to generate the TOC XML navigation files and use the Javadoc generated by developer. The article presents the solution using the standard Javadoc Generation wizard to create Javadoc for Java API reference documentation and the JavaTOC doclet for the TOC XML navigation files in an Eclipse development environment.

This article presents how to run the JavaTOC doclet in Eclipse through the Custom doclet wizard, and second through the Ant build system. If you haven't worked with Ant, check out the Jakarta website, or "Open Source Java: Ant".

Workflow

Add the JavaTOC plug-in build tools (JavaAPITools) into your workspace:

• Find the workspace directory used by your version of Eclipse. Typically this is located inside the directory in which Eclipse was installed in a subdirectory called "workspace". If you are using a shortcut or script to launch Eclipse, then it will be under the current working directory of that shortcut or script in a subdirectory called "workspace".
• Download and unzip the package (JavaAPITools) into your workspace. This will create a "JavaAPITools" project.
• Import the "JavaAPITools" project and the Java project you want to work with into your Eclipse workspace.

Use the Import Wizard to import an existing Java project into workspace. For this example, I created a new Java project "org.dita.dost" and added to the source code (src folder) from the DITA Open Toolkit source code, which transforms DITA content (maps and topics) into deliverable formats. You can download this plug-in from the Download resources.

Creating Javadoc documentation using the Eclipse Javadoc Generation wizard (Standard Doclet)

The following steps show how to generate Javadoc in an Eclipse development environment using the Standard Javadoc Doclet:

• In Eclipse, on the left pane, select the source code plug-in for which Javadoc needs to be generated.
• Right-click on the selected plug-in, and from the drop down list select Export. The Export window opens.
• Select Javadoc and click Next. The Generate Javadoc window opens.
• In the Generate Javadoc window select the packages that you want to export to the JAR file. This list is initialized by the workbench selection. Only one project can be selected at once as only one project classpath can be used at a time when running the Javadoc tool. (Figure 1)
• Select members visibility (normally Package and Public).
• Select Use Standard Doclet to start the Javadoc command with the standard doclet (default).
• Destination: select the destination to which the standard doclet will write the generated documentation. The destination is a doclet specific argument, and therefore not enabled when using a custom doclet.
  The destination to which the standard doclet will write can be for example "doc.dita.dost.doc\topics" (Figure 2)

• Click Finish to generate Javadoc, or click Next to specify additional Javadoc generation options.

NOTE: For more informations see Javadoc generation — Eclipse Help Platform

Destination directory for output files

• The doclet generates the output HTML files for the plug-in documentation to "org.dita.dost\org.dita.dost.doc\topics\", which is now your plug-in documentation directory.

Back to top

Creating TOC XML navigation and Javadoc plug-in files using the Eclipse Javadoc Generation wizard and JavaTOC doclet (Custom Doclet)

The following steps show how to use the customized doclet, the JavaTOC doclet, in combination with Javadoc in an Eclipse development environment:

• In Eclipse, on the left pane, select the source code plug-in for which Javadoc needs to be generated.
• Right-click on the selected plug-in, and from the drop down list select Export. The Export window opens.
• Select Javadoc and click Next. The Generate Javadoc window opens.
• In the Generate Javadoc window select the packages that you want to export to the JAR file. This list is initialized by the workbench selection. Only one project can be selected at once as only one project classpath can be used at a time when running the Javadoc tool.
• Select member's visibility (normally Package and Public).
• Select Use Custom Doclet and add the Qualified type name of the doclet to the Doclet name: com.ibm.malup.doclet.config.DITADoclet , and the Classpath needed by the doclet class to the Doclet class path: <eclipse_workspace>\JavaAPITools\bin\JavaTOC.jar
  NOTE: <eclipse_workspace> is the absolute path for the Eclipse Workspace (C:\eclipse\workspace).
• Destination: select the destination to which the standard doclet will write the generated documentation. The destination is a doclet specific argument, and therefore not enabled when using a custom doclet.
  The destination to which the standard doclet will write can be for example "doc.dita.dost.doc\topics"
• Click Next.

Extra Javadoc options

• For the Extra Javadoc options (path names with white spaces must be enclosed in quotes); add the content from the Listing 1. (for our example org.dita.dost plugin).
1. -d <destination_directory> Specifies the destination directory for the generated documentation. By default, this is the current directory (the one designated by "." pathname).
2. -pluginid <plugin_id> Include id for the Eclipse plugin id page.
3. -doctitle <html_code> Include title for the Eclipse plug-in name page.
4. —overview <file> Specify the plugin version id details.
5. —version <plugin_version> Specify the plugin version id details.
6. -provider <plugin_provider> Specify the plugin provider name details.
7. -anchor <file> Linking is specified by using the fully qualified reference to a table of contents, such as: "../the_other_plugin_id/path/to/toc.xml#anchor_id"
8. -notree If you are going to generate documentation for a big project, specify to create multiple XML TOC files.

                
-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
      

Destination directory for output files

• The doclet generates the output TOC XML files for the plug-in, and other several useful files in the org.dita.dost\org.dita.dost.doc\ folder, which is now your plug-in directory. The files created by the JavaTOC doclet are:
  • plugin.xml
  • plugin.properties
  • build.properties
  • .project
  • META-INF\MANIFEST.MF
  • primary.plugin.toc.xml
  • org.dita.dost.xxx.toc.xml— TOC XML file for building the navigation tree in the help browser
• The plug-in's name, id, version, and provider-name values are auto-generated from the -d, -doctitle, —version and —provider properties.
• The plug-in manifest files externalize their strings by replacing the string with a key (e.g. %pluginName) and creating an entry in the plugin.properties file of the form: Plugin.name = Online Help Sample Plugin

Back to top

Using the JavaAPITools (build.xml & JavaTOC doclet) and ANT to create your documentation plug-in

The main purpose of the JavaAPITools is to create a NEW DOCUMENTATION plug-in with Javadoc for the public API reference documentation and all Eclipse plug-in files necessary to integrate this Java API reference documentation with the Eclipse Help system, inclusive the TOC XML navigation files for Javadoc.

Installing the plug-in build tools (buildAPITools)

The JavaAPITools package, provides an Eclipse build script for creating Eclipse documentation plugins. The script lets you transform Java project plug-ins within Eclipse and use the Eclipse target runtime for testing them. The generation of the Javadoc is accomplished by creating an ANT script in your plug-in called build.xml. This ANT script requires the JavaAPITools build.xml build tools which must be located somewhere on your development system (workspace). Also, the script must be able to determine how the resulting xxx.doc plug-in is to be packaged for deployment.

• Download the package, create a 'JavaAPITools' project in your workspace, and unzip the package into the project.
• Import the plugins you want to work with into your Eclipse workspace. For this example I created a new Java project and I added to the src folder the source directory from the DITA Open Toolkit source code which transforms DITA content (maps and topics) into deliverable formats. You can download this plugin from the Download resources, or you can run on your project example.

Determine the plug-in deployment packaging

Before Eclipse 3.2, the generated Javadoc would be kept in a doc.zip file along with the HTML files. Since 3.2, the entire documentation plug-in can be shipped as a single .jar file that includes all of the files that would go into the doc.zip file along with the Eclipse plug-in files: manifest.mf, plugin.xml, plugin.properties, etc.

Since Eclipse 3.1, plug-ins can be deployed either as a directory containing separate files (including one or more jar files), or a plug-in can be deployed as a single jar file.

                
bin.includes = META-INF/,\
               .project,\
               plugin.xml,\
               toc.xml,\
               plugin.properties,\
               doc.zip,\
               bin/
      

Comment: If the original plug-in is to be deployed as a directory, the build.properties file should include the doc.zip file. If the plug-in is to be deployed as a single .jar, the build.properties should NOT contain doc.zip but should contain the droot directories and files that would have been created within a doc.zip file.

In addition, the .doc-feature plug-in that includes such a doc plug-in must also contain the unpack="false" attribute in the feature.xml file for the plug-in.

Create, manage, and run the ANT build file

• Right click build.xmll from builAPITools and select Run As > External Tools, and in the Builders section, select New Lunch Configuration .. and create a new Ant Build configuration.
• In the resulting configuration dialog, set the name to something unique (e.g., Build Plugin Documentation). In the launch configuration Main tab, browse the workspace and select the build.xml file from the JavaAPITools). Add to the Base directory the value: ${project_loc}.

The following diagram, Figure 5, shows the Main tab of the ANT launch configuration dialog.

• Arguments:
  • The —verbose argument allows you to track the information about a specific command that isn't working. The —quiet argument suppresses most messages not originated by an echo task in the buildfile, and -debug, prints debugging information in Eclipse Console.
  • The —Dbuild.toc.tree=true argument overrides —build.toc.tree property and assigns the value to true before the build script is executed. This will create only one primary TOC XML file (xxx.toc.xml) in place of multiple file.

Creating build.xml ANT file

The build.xml script defines all of the information needed to generate the Javadoc for the associated component plug-ins and either creates the doc.zip file or copies the generated files into the root of the plugin. For complete documentation on the tasks that can be used in this file, see JavaAPITools/build.xml.
The initial contents of this file should be:

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

Auto-building the plug-in

• Highlight your plug-in project.
• Click Run > External Tools > External Tools > Build Plugin Documentation.
  • The build runs, with running commentary and errors appearing in the Console view.
  • If you get a 'BUILD FAILED' error in your console, check and fix any problems that occur and build again, until you get a 'BUILD SUCCESSFUL' at the bottom of the console message.
  • After a successful build (in your development environment) of the doc plugin (no more ANT errors) there should be a \topics folder for the HTML files, and there should be a doc.zip file in the root directory and the plugin manifest file.
  • The build properties will include all of the toc*.xml files, plugin.properties, META-INF, and .project files. If a doc.zip file was created, the build.properties file will also include the doc.zip (do not modify). If the plug-in is to be deployed as a single jar file, the build.properties file must also include the top level directories that were created (topics), and not the doc.zip file.

Destination directory for output files (org.dita.dost.doc)

• For our example (org.dita.dost.doc plug-in), the ANT buildfile generates the output XML files for the plug-in, and several other useful files to workspace\org.dita.dost.doc directory, which is now your plugin directory.
• Modifying the value for the build.toc.tree from false to true. The ANT buildfile generates the output in two ways:
  
  

  <property name="build.toc.tree" value="false" />

  <property name="build.toc.tree" value="true" />

  .project plugin.xml plugin.properties META-INF\MANIFEST.MF topics\ — All HTML files. 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 files for building the navigation tree in the help browser buildJavaDoc.bat — BAT file for running JavaDoc tool.

  .project plugin.xml plugin.properties META-INF\MANIFEST.MF topics\ — All HTML files. doc.zip org.dita.dost.doc.toc.xml — Primary TOC XML file for building the navigation tree in the help browser. buildJavaDoc.bat — BAT file for running JavaDoc tool.

  
  
  
• You can modify the ANT build files to add more futures:
  • On the Java project plugin.properties add 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

    
    
  • On the build.xml add
    
    
    
    

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

    
    

Importing the plug-in into your workspace

You can use the Import Wizard to import the documentation plug-in into your workspace.

• From the main menu bar, select File > Import.... The Import wizard window opens.
• Select General > Existing Project into Workspace and click Next.
• Select the root directory and click Browse to locate the Workspace directory
• Under Projects select the org.dita.dost.doc project to import.
• Click Finish to start the import.

Back to top

Testing the Java API reference plug-in

• Set up the target runtime environment:
  • Select Window > Preferences > Plug-in Development > Target Platform
  • Set Location to be the main eclipse directory within your externally-installed product. A list of plugins in the Eclipse directory appears (this step takes a while).
  • Click OK to save the Target Platform settings.
• From the Plugin Development perspective, create a Run configuration by selecting Run > Run . This will launch the Run configuration page.
  • Click Eclipse Application configuration then the New button, and name it anything to identify it as the testing JavaTOCdoclet Eclipse Plugin. We'll call it Test Plugin Doc.
  • On the Main tab, under the location field, select a workspace directory. Things that you do while using the target runtime will be written to that workspace, including the .log file in the .metadata folder
  • Under Program to Run, select Run a product and choose org.eclipse.platform.ide
  • On the Plug-ins tab, select Choose plug-ins and fragments to launch from the list
  • Under Workspace Plug-ins, select the plugins that you want to test. This option allows you to test your local plugins, even if the plugin is new and not installed with the target runtime.
  • Leave the External Plug-ins list as it is.
  • Select the Add new workspace plug-ins to this launch configuration automatically check box.
  • Click Apply to save the changes.
  • Switch to the Plug-in Development perspective and click Run > Run .
    • Select the Run configuration that you created (Test Plugin Doc) and click Run. The target runtime will launch. This means that your external product will start, but will have a copy of your local plugins instead of the version that is in the product.
    • NOTE: Once you run your plugin once, the Run configuration (Test Plugin Doc) will appear in the Run History, so you can launch the target runtime with Run > Run History > Test Plugin Doc, or you can use the toolbar icon .
    • 
    • The defaults will launch every plug-in in the target platform plus all open plug-in projects in your workspace. This and the other defaults are sufficient.

Back to top

Viewing your Java API reference documentation

From the new Eclipse Test Platform, select Help > Help Contents. You will get a help window, Figure 9, with your plug-in added (similar to the one in Figure 2).

Back to top

Packaging the plug-in

Once you have done this, all you need to do is package everything in the structure using the Workbench User Guide, Export wizard. This wizard helps you to export resources from the Eclipse workbench.

Back to top

Notices

• The information provided in this document are my observations and techniques as a technical writer, and has not been submitted to any formal IBM test and is distributed "AS IS," without warranty of any kind, either express or implied.
• The JavaTOC doclet tool is a published invention, author Mariana Alupului. The invention is part of the IBM Intellectual Property and it is published on www.ip.com.
• The use of this information or the implementation of any of these techniques described in this document is the reader's responsibility and depends on the reader's ability to evaluate and integrate them into their operating environment.

Back to top

Conclusion

The JavaTOC Doclet presented in this paper can be used to produce help documentation based on HTML and a small number of additional documentation elements. Using this doclet, it is easy to create Eclipse platform documentation, which can then be used to produce XML and HTML output formats for existing Eclipse help systems.

I have shown you how to develop Eclipse platform documentation using JavaTOC doclet, and not how to document the source code. The generated documentation should be professional quality so you need to do your most important job; to fully document the developer source code for fully documented Java API references. This free open source solution can simplify your documentation development process, allowing you to work just with a doclet and have the plug-in structure, the TOC navigation and HTML files generated for you.

In the upcoming articles of developerWorks XML zone series, I will describe a process for automatically generating searchable Java API documentation (TOC navigation) using the DITAdoclet tool for the Eclipse Plug-in Help System. The How Java API Documentation is organized in DITA API specialization will provide the DITAdoclet tool for download and explain how to use it to generate the Java DITA API files and the XHTML output from the Java source code. We will also look more in-depth at the Java API reference documentation technology, and some of the value-added enhancements from IBM such as Java DITA API specialization, and how it can be utilized.

Back to top

Downloads

Information about download methods

Resources

Learn

• Lean more about Sun Microsystems Javadoc tool.
  • See the Javadoc home page for more information about Sun Microsystems Javadoc tool.
  • Explore Doclet.com, a repository of Doclet extensions for the Javadoc tool.
  • The Sun tutorial "How to Write Doc Comments for the Javadoc Tool" describes the rules and philosophy of Javadoc.
  • The Javadoc doclet API lets you write custom Javadoc plug-ins to produce different forms of documentation, HTML, XML or DITA from Javadoc comments.
  
  
• Find more XML resources on the developerWorks XML zone. The developerWorks XML zone contains literally hundreds of articles, tutorials, and tips to help a developer make the most of XML-related applications, but for users trying to find their way in a new topic, all of that information can be overwhelming.
  • Documentation Enhancer for Java from IBM alphaWorks is a tool that enhances Javadoc files by enriching them with new information (semantic information, sorting, and navigability) that is gathered by statically analyzing the corresponding Java class files.
  • See the "Documenting your project using the Eclipse help system" , from IBM developerWorks.
  • The Java language takes an integrated approach to API documentation through the Javadoc comment convention.
    Read David Gallardo article, "Java theory and practice: I have to document THAT?" and learn how to create Eclipse plug-ins using the Plug-in Development Environment's code generation wizard.
  
  
• Find more resources on the Eclipse Platform . Eclipse is an open source community whose projects are focused on providing an extensible development platform and application frameworks for building software.
  • See Javadoc generation wizard allows you to generate Javadoc Generation. It is a user interface for the javadoc.exe tool available in the Java JDK.
  
  
• The DITA Open Toolkit is an implementation of the OASIS DITA Technical Committee's specification for Darwin Information Typing Architecture (DITA) DTDs and Schemas. The Toolkit transforms DITA content (maps and topics) into deliverable formats.
  • Find more about the "DITA XML Specialization for Writing Language-conformant Reference Documentation for API libraries".
  • Find more about the "Java API Reference Specialization" which provides a basis for documenting Java class libraries.
  
  

Get products and technologies

• The DITA API Specialization (javaapiref0.8.zip ) can be used or examined as an example of how to extend the generic API Reference specialization
  
  

Discuss

• Find more about the collaboration between the developers and the writers in my "API documentation process series article"
  • "Creating Javadoc API documentation with directly updated source"
  • "Creating Javadoc API documentation with indirectly updated source".
  
  
• Part 1 of this series, "Javadoc API reference documentation"
  • "How Java API reference documentation is organized in Eclipse Help"
  
  

About the author

Mariana Alupului is a senior technical writer (API) for IBM Software Group, Rational Software. In addition to documenting and leading API documentation projects for Java, VB, C++ in software programming environment, she is a member of the IBM Corporation team that develops the Darwin Information Typing Architecture (DITA) XML specialization for writing language-conformant reference documentation for API libraries. Mariana helps to create the API reference style guidelines and is a member of the corporate ID-Support Council and ID Technical Writers Council. She is a member of the Society for Technical Communication and has presented at the "Beyond the Bleeding Edge" session in 2005.

Comments

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Quick Review
• Generate Eclipse Plugin (Javadoc API reference documentation) using JavaToc doclet
• Design Constraints
• Workflow
• Creating Javadoc documentation using the Eclipse Javadoc Generation wizard
• Creating TOC XML navigation and Javadoc plug-in files using the Eclipse Javadoc Generation wizard and JavaTOC doclet (Custom Doclet)
• Using the JavaAPITools (build.xml & JavaTOC doclet) and ANT to create your documentation plug-in
• Testing the Java API reference plug-in
• Viewing your documentation
• Packaging the plug-in
• Notices
• Conclusion
• Downloads
• Resources
• About the author
• Comments

Next steps from IBM

Spring, JRuby, and Ajax development is easier with WebSphere Application Server - a smart Java 5 and J2EE Web services-based application server.

---

• Try: The no-charge WebSphere Application Server Community Edition is a pre-integrated, lightweight Java 5 application server built on Apache Tomcat and other best-of-breed open source software such as OpenEJB, Apache Axis, and Apache Derby.
• Article: The article leverage the Spring Framework and the WebSphere Application Server to improve your J2EE project productivity.
• Tutorial: See how the free WebSphere Application Server and XML can improve the efficiency of your JRuby on Rails and Ajax development.
• Buy: WebSphere Application Server - Express

My developerWorks community

Dig deeper into Rational on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers