Integrating Javadoc (API Reference) with JavaHelp (Online Help): Two Approaches
This article discusses two approaches for integrating Javadocs (the automatically generated documentation for Java code) with a traditional online help system (sometimes implemented as a JavaHelp system). The two approaches are Surface (or "shallow") and Nested (or "deep").

Although online help (either task-based or UI-centric) and API reference documents serve different purposes, there are times when you may want to at least create associations between the two or at most merge them into one system. This may be especially true if your users are programmers or developers who may be accustomed to digging through the API reference as much as any part of the documentation for specific information. In the case of Java documentation the two types of documentation are very separate but integrating them can be done.

Surface Approach
In the "surface" (or "shallow") approach, I simply add a link to the Javadocs from the online help's table of contents. JavaHelp allows content providers to seamlessly combine and integrate different helpsets. This is automatic and requires no work by the author (other than to include the sub-helpset).

To add this table of contents entry, simply create a new helpset (for example, api.hs to represent the Javadocs(. Essentially, this new helpset is empty, except for the contents (toc.xml) declaration:
<xml version='1.0' encoding='ISO-8859-1'?>
<toc version="1.0">
<tocitem text="API Reference (Javadoc)" target="link or targeted for the Javadoc" />
</toc>

Then add this as a sub-helpset to your main helpset:
<?xml version='1.0' encoding='ISO-8859-1'?>
<helpset>
<subhelpset location="welcome.hs" />
<subhelpset location="gettingstarted.hs" /> <!-- Getting Started Guide -->
<subhelpset location="userguide.hs" /> <!-- User's Guide -->
<b>&lt;subhelpset location="api.hs" /></b> <!-- Javadoc -->
</helpset>

This figure illustrates the "Shallow" method:
Surface.approach
Surface.approach



Pros: Very easy to implement, by adding a new to your main helpset file, including the Javadoc as a table of contents item. Requires no coordination between help author and Javadoc author. No maintenance issues.

Cons: No direct relationship between help content and Javadoc — Javadoc appears as a "separate" document.



Contributors to this page: Rick Sapir .
Page last modified on Tuesday, October 26, 2004 10:20:00 pm EDT by Rick Sapir.

Key Pick New

Bill Albing has some suggestions to improve STC competitions. Read and let us know, what do you think?

Other Key Picks... Read more

About KeyContent

About KeyContent
KeyContent.org is an idea space where you can express your insights about your profession. Think of this site as a white board with a brain. You create and edit articles or portals to other sites and share your insights... Read More


Key Ads

Key Connections

Join KeyContent on these networks:



Key Products

Make Custom Gifts at CafePress

Key Promotions