 | Level: Intermediate Mariana Alupului (malupulu@us.ibm.com), Information Developer, Rational software, IBM
26 Dec 2007 This article, Part 2 of a series, describes different approaches for generating easy-to-use and searchable Java application programming interfaces (API) reference documentation.
Quick Review
In Part 1 of this series,
How Java API reference documentation is organized in Eclipse
Help
, I introduced a different approach for generating easy-to-use and searchable
Java application programming interfaces (API) reference documentation.
This article discusses the JavaTOC doclet tool, how to use it and how to extend it. The approach uses the Javadoc standard
solution and the Eclipse Plug-in Help System generated using the JavaTOC doclet
that I developed. The JavaTOC doclet tool generates the necessary XML table-of-contents (TOC)
navigation files for the Eclipse Help system, and the Sun Javadoc API reference
documentation in HTML format. To understand the approach, I included a demo
example that uses the Sun Javadoc and the JavaTOC doclet tool (using Command
Prompt).
Eclipse Javadoc API
reference structure generated with JavaTOC doclet
Design Constraints
| |
To become a highly skilled Technical Writer (Java API Information Developer),
you must acquire a fluent understanding of the Java language, Java API reference
documentation generation tools and techniques.
|
|
You can run JavaTOC doclet and Javadoc to generate
the Java API reference documentation, the table of contents (TOC) navigation
and the plug-in structure. Or, you can run just the JavaTOC doclet to generate
the TOC navigation from the existing documentation that was produced by developer
and delivered to you.
Workflow
For each plug-in that you want
to contribute to Eclipse help system (Java API reference section), should
in general, proceed with the following workflow:
- Run JavaTOC doclet to create all necessary plug-in files for the Eclipse
Help system (plugin.xml, primary.plugin.toc.xml, META-INF/MANIFEST.MF, build.properties,
and plugin.properties).
The plugin.xml file, which extends the org.eclipse.help.toc
extension point, needs to specify:
- One XML TOC file, if you have just a couple of Java packages.
- Multiple XML TOC files, when you have multiple Java packages.
- Run Javadoc (Sun Microsystems, Inc.) on your Java source code files to
create the HTML files for the Java API reference documentation.
- Test the Java API reference documentation that was generated.
Ant is the Java build system that everyone seems to be using now.
If you haven't worked with Ant, check out the Jakarta website, or "Open Source
Java: Ant".
My preferred way to run the JavaTOC doclet tool
is through the Ant build system, but in this article I will show you how to
use JavaTOC doclet from Command Prompt.
Building XML TOC files output with command line
| |
Computer programming languages support source code documentation, by
providing special symbols that signal the beginning and end of source code
descriptions. The symbols and descriptions are collectively known as comments.
Java programming language supports three styles of comments: multiline, single-line,
and doc.
|
|
The JavaTOC Doclet Toolkit release 1.0.0 provides
a Command Line interface as an alternative for users with little knowledge
of Ant to easily use the toolkit.
- Ensure Javadoc is installed on your path. (...\jdk1.5.0_06\bin\javadoc.exe)
- NOTE: Typically, Javadoc will have a path like C:\Program Files\Java\jdk1.5.0_06\bin.
- Download the JavaToc Doclet ZIP file
and unzip the zip file into a directory of your choice (for example, C:\doclet\
on Windows). It will create a directory JavaTOC with bin\, demo\ and doc\
subdirectory.
- The bin directory contains the Java classes you need to run the
doc expansion as jar libraries. (DocletTOC.jar)
- The doc directory contains the JavaTOC User Guide and the org.dita.dost.doc plugin
API Documentation (an example) in HTML format.
- The src resources directory contains the Java source files that
you can use for the example.
(you can download the source files directly
from the SOURCEFORGE website: DITA-OT1.3_src.zip )
- Use the @packages option to place the packages fully qualified type
name in a separate file.
- Run the following command from directory c:\doclet> javadoc @tocdoclet
@options @packages (Listing 1 thru Listing 3)
Listing1. tocdoclet
-doclet com.ibm.malup.doclet.config.TOCDoclet
-docletpath C:\doclet\bin\TOCNavDoclet.jar
|
Listing2. 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' |
Listing 3. packages
com.ibm.package1
com.ibm.package2
...
com.ibm.packageN
|
Listing 4. removefiles
source\..\..\package1\fileA.java,source\..\..\package2\fileB.java, , ,
source\..\..\packageN\fileN.java |
- You can modify this files by opening them with NotePad editor.
- JavaTOC doclet passes the plug-in name, id, version, and the provider-name
values to your Eclipse plug-in project, shown in Listing 2.
The extension
point from the org.eclipse.help.toc plug-in identifies this as a plug-in to
the help system.
The file doclet.toc.xml is referenced as being the
table of contents for this plug-in; this file will provide the data for the
hierarchical information in the left pane of the Eclipse help window.
- The packages file contains something like what is shown in Listing
3.
- Running the command: javadoc @tocdoclet @options @packages @removefiles —
remove all the classes that you do not want to be exposed (Listing 4).
Table of supported parameters provided by JavaTOC doclet:
- The doclet generates the output XML files for the plug-in, and several
useful files to c:\doclet\com.ibm.doc_plugin_name, which is now your
plug-in directory:
- plugin.xml
- plugin.properties
- .project
- META-INF\MANIFEST.MF
- com.ibm.packageN.toc.xml — TOC XML files for building the navigation tree
in the help browser
- buildJavaDoc.xml — ANT file for running JavaDoc tool from the Ant environment.
- buildJavaDoc.bat — BAT file for running JavaDoc tool.
- Run JavaDoc from Command Prompt (buildJavaDoc.bat) to create HTML file
for API Documentation.
Using
the JavaTOC doclet to create one XML TOC file
Now that
we have talked about the doclet, let's get into the real example using the
JavaTOC doclet with the DITA-OT 1.3 source files (DITA-OT1.3_src.zip) as our
example.
A TOC file defines the key entry points into the HTML content
files by defining labeled topics mapped to the individual HTML files, and
acts like a table of contents for a set of HTML content. This TOC files are
sometimes referred to as navigation files since they describe how to navigate
the HTML content. A plug-in can have one or more TOC files.
Running org.dita.dost
example
Running the bat file: C:\doclet\JavaTOC>TOCDoclet_dost.bat (Listing 5 thru Listing 8)
Listing5. TOCDoclet_dost.bat
javadoc @config @options @packages |
Listing6. config
-doclet com.ibm.malup.doclet.config.TOCDoclet -docletpath C:\doclet\bin\TOCNavDoclet.jar
|
Listing 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 |
Listing8. 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
|
or from Command Prompt C:\doclet\JavaTOC> directory:
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
Destination
directory for output files
- The doclet generates the output XML files for the plug-in, and several
useful files to C:\doclet\JavaTOC\output\org.dita.dost.doc, which is
now your plug-in directory (Listing 9):
- plugin.xml
- plugin.properties
- .project
- META-INF\MANIFEST.MF
- org.dita.dost.doc_toc.xml— TOC XML file for building the navigation tree
in the help browser.
- buildJavaDoc.xml — ANT file for running JavaDoc tool from the Ant environment.
- buildJavaDoc.bat — BAT file for running JavaDoc tool.
Listing9. 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> |
The plug-in's name, id, version, and provider-name values are
auto-generated from the -d, -doctitle, —version and —provider properties (Listing 10).
Listing10. plugin.properties
# NLS_MESSAGEFORMAT_VAR
# ==============================================================================
# Online Help - Translation Instruction: section to be translated
# =============================================================================
Plugin.name = Building DITA output
Plugin.providerName = IBM |
The plug-in manifest files externalize their strings by replacing
the string with a key (e.g. %pluginName) and create an entry in the plugin.properties
file of the form: pluginName = "Online Help Sample Plugin" (Listing 11)
Listing11. 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
|
The extension point of the org.eclipse.help.toc plug-in identifies
this as a plug-in to the help system. The file doclet.toc.xml is referenced
as being the table of contents for this plug-in; this file will provide the
data for the hierarchical information in the left pane of the Eclipse help
window.
A simple file contains something like what is shown in Listing
12.
Listing12. 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> |
Now we have all plug-in files, which have been tagged
for Eclipse Help system. You have the structure for the Java API reference
documentation that enables navigation within an Eclipse help plug-in through
a table-of-contents (TOC) written as an XML document. The browsable and searchable
needs are met with this structured information approach using XML.
The
documentation is provided with a collapsible index on the left side, and HTML
documentation on the right
Running JavaDoc to create HTML file
Run
JavaDoc from Command Prompt from C:\doclet\JavaTOC\demo\output\org.dita.dost.doc
directory (buildJavaDoc.bat) to create the HTML files for the API reference
documentation.
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
Using the JavaTOC doclet to create multiple XML TOC
files
A single Java API can typically consist of seven
or more package files. With JavaTOC doclet, you only maintain one file (package.txt),
and the rest is generated. You dramatically reduce development time, and can
concentrate on documenting the API, while JavaTOC generates 100% of the plug-in
help code for you.
Running same org.dita.dost example
Run
Command Prompt JavaTOC doclet from C:\doclet\ directory.
C:\doclet\JavaTOC>javadoc
@tocdoclet options.org.dita.dost @packages
(Listing 13)
Listing13. 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 |
where I introduce the -notree parameter:
|
Parameter
|
Description
|
| -notree | Specify to create multiple XML TOC files
NOTE: Missing this parameter
will create only one XML TOC file. |
or
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
Destination directory for output files (org.dita.dost.doc)
- The doclet generates the output XML files for the plug-in, and several
useful files to C:\doclet\JavaTOC\demo\output\org.dita.dost.doc. This
is your new plug-in directory:
- 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 files for building the navigation
tree in the help browser
- buildJavaDoc.xml — ANT file for running JavaDoc tool from the Ant environment.
- buildJavaDoc.bat — BAT file for running JavaDoc tool.
The file org.dita.dost.index.toc.xml is just another table of
contents, and should take exactly the same format as any other toc.xml file (Listing 14).
Listing14. 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>
|
where "doclet.toc.xml" is the primary file. The important
thing here is to define this table of contents as a primary toc (Listing 15).
Listing15. 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>
|
When the documentation is viewed, there will be no difference
between using this method and simply including the additional topic elements
directly (Listing 16).
Listing16. 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>
|
Having edited or added new API documentation to a source
code file, you should generate the documentation to ensure and test that the
result is what you expected.
Now take your plug-in and drop it into
the Platform’s plugins directory, start Eclipse and choose Help -> Help Contents.
Running
JavaDoc to create HTML file
To generate the Java API reference
documentation (HTML format) for our example (org.dita.dost):
- Run the javadoc utility on the Java code by executing the command, or
- Run buildJavaDoc.bat batch file (Listing 17).
Listing
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 |
Packaging the plug-in
Each topic element
is represented in the final documentation by an entry in the navigation list.
These topics can be nested (they can contain more topics), and each one points
to an HTML file. Once you've done this, all you need to do is package everything
in the structure shown in Figure 1 (notice that the plug-in directory name
matches the id and version attributes of the plug-in defined in the plugin.xml).
Figure 1. Plug-in directory
As
a convenience, and to reduce file size, Eclipse allows you to keep all your
actual documentation (the HTML files) in a ZIP file called doc.zip, so you
could use the directory structure shown in Figure 2.
Figure 2. Directory structure of doc.zip
Viewing your documentation
The easiest way to test
your plug-in is to simply drop the entire directory (as above) into the plugins
directory of an installed Eclipse Platform, and then launch Eclipse and select
Help > Help Contents. You will get a help window with your plug-in added (similar
to the one in Figure 3).
Figure 3. Help — Eclipse
SDK
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.
Conclusion
| |
The Java API reference source is owned by programmers, and edited by
both programmers and technical writers.
|
|
The JavaTOC doclet presented in this paper
can be used to produce Java API reference 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.
We have shown how to develop Eclipse platform documentation using the JavaTOC
doclet. This free open source solution can simplify your documentation development,
allowing you to work just with a doclet and have the plug-in and the reference
documentation generated for you. Over time, there will be more and more additions.
In the upcoming articles of developerWorks XML zone series, How Java API Documentation
is organized in DITA API specialization, 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. We will also
look more in-depth at the Java API technology, and some of the value-added
enhancements from IBM, including Java DITA API specialization, and how it
can be utilized.
Download | Description | Name | Size | Download method |
|---|
| Java Toc file | JavaTOC.zip | 108KB | HTTP |
|---|
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.
- 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.
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"
- Part 1 of this series, "Javadoc API
reference documentation"
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. |
Rate this page
| |
Include the title for the Eclipse plug-in.
