RE: API/javadoc - classes/methods that should not be public

[David Price <price -at- ontos -dot- com>]

Thanks to all who responded to my query about how to deal with public Java
classes that should not really be public in an API. The consensus seemed to
be for link completeness, with some variations on what to do about all the
dirty linen thus exposed. I decided to add the comment "Not intended for
general use; currently unsupported," for every public class and method that
shouldn't be public. 

A couple of things are worth mentioning, which might save someone else some
headaches or give others some ideas -- also, answers a few questions that
were asked. The following applies to those who are generating Javadoc and,
optionally, importing that into HTML Help:

* I added the aforementioned comment as the first sentence, in front of
whatever programmer comments were already there. Advantage: In method
summaries, you only see my comment, but the programmer's comments are
retained for those who want to go spelunking into the detail. 

* I generate two versions of the Javadoc. 1) Stand-alone version, to be used
in IDE or wherever Javadoc is normally used (nice F1 ability in JBuilder
with no added effort on my part, for example). Generate this version with
all the navigational bells & whistles. Works great on web. 2) Version to be
imported into HTML Help. Generate with minimal options, no navigation. 

* I used Doc+ to add comments to the source, which presents a kind of
Javadoc window on the source so you can focus on just the comments, rather
than the code. It's not free, but well worth the $200-something if you're
doing lots of Javadoc stuff. 

* When you import Javadoc into HTML Help through RoboHTML, all the methods
come over as topics, BUT, there are problems with methods that have more
than one argument due to the space in the topic title. Problem: links to
those topics don't work (goes to the beginning of the class where that
method lives). Solution: had a developer write a little program to blow
through all the Javadoc HTML before importing it, removing spaces from
method arguments. Worked great, but adds a step to the process.

* I used k-links from the Programmer's Guide to specific methods in the API
(am using Robo Classic for all books except the API). Clutters the index
somewhat, but A-links don't work for specific methods, unfortunately. Also,
since a-links are added to the HTML page, I didn't use them in other
situations because I wanted to be able to regenerate from the Javadoc and
re-import into the project without having to redo links. 

* Created a style sheet for the Javadoc that matches the style sheet used
for all the other doc (specify it using a parameter when you generate the
Javadoc). In the merged HTML Help, you can't tell what was Javadoc-generated
and what was not. Also, when used stand-alone, the Javadoc stands out a
little bit compared to the average, because most people just use the
defaults (looks better than Sun's, for example). 

* Take advantage of the "overview" feature of Javadoc. This allows you to
write separate HTML overview pages for packages and classes. These pages are
not part of the source, but they get sucked into the output (if specified).
You can get pretty windy in there if you want, without annoying the
developer.

* Also, take advantage of the "doc-files" feature of Javadoc for creating
examples, tutorials, graphics, etc., that you don't want to put in the
source. You can link to this stuff from the source wherever necessary.

Hope this is useful info -- sorry for the length. Email me if you have any
questions.

- David


> Doing a little poll here, trying to figure out which way to go. I'm
> documenting an API using javadoc, importing it into HTML Help as the
> reference piece of a Programmer's Guide. There are a number 
> of classes &
> methods declared public that should not really be public 
> (utility classes,
> etc.). These classes/methods are "undocumented," meaning 
> there may or may
> not be comments in there, and they may or may not make sense. 
>  There is no
> option in javadoc (yet) to exclude these. I see two options:
> 
> 1. Import the whole thing, let the chips fall where they may. 
>  Advantage:
> structural completeness, no broken links. Disadvantage: some 
> garbage, some
> empty classes/methods.  I'm not linking directly to any of 
> these methods
> from within the main doc, so someone might stumble across 
> them only if they
> start following links within the meat of the API doc.
> 
> 2. Remove the html files for those classes that shouldn't be 
> public before
> importing in HTML Help. Advantage: everything has been looked 
> at, reviewed,
> etc., and is reasonably accurate. Disadvantage: broken links.
 
 

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

Sponsored by Information Mapping, Inc., a professional services firm
specializing in Knowledge Management and e-content solutions. See
http://www.infomap.com or 800-463-6627 for more about our solutions.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.