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

["Glenn Maxey" <glenn -dot- maxey -at- voyanttech -dot- com>]

I vote for completeness.

If they really aren't supposed to be used, create (or pressure the owning
engineering to create) a Javadoc comment in the code that says precisely
that. "For internal use only," "Don't use this directly," "Use at your own
risk," or whatever else is applicable.

Then, even if it is exposed from exploring the API, your audience will be
happy (a) that your documentation was complete, and (b) that they were
warned about what not to use.

I don't recommend removing things by hand (your option 2), because you'll
have to do that each time Javadoc runs. And you get the broken links.

My suggestion is a version of your option 1. Where it is different in that
there is no garbage, just things that the user sees but isn't supposed to
use.

When I documented API's at a previous company, if we couldn't exclude things
because they were private, our documentation explicitly told our audience
not to use it and what to use instead.

BTW, I'm using Doxygen at my present company. I'm using the JavaDoc style. I
understand that the latest version of Doxygen supports Java. (Doxygen is
shareware.) The reason I bring this up is that Doxygen has a few more
commands than JavaDoc. One in particular is "@internal" which can be used to
hide things.

HTH,

Glenn Maxey
Voyant Technologies, Inc.
Tel. +1 303.223.5164
Fax. +1 303.223.5275
glenn -dot- maxey -at- voyanttech -dot- com



> -----Original Message-----
> From: bounce-techwr-l-58477 -at- lists -dot- raycomm -dot- com
> [mailto:bounce-techwr-l-58477 -at- lists -dot- raycomm -dot- com]On Behalf Of David Price
> Sent: Friday, April 20, 2001 2:52 PM
> To: TECHWR-L
> Subject: API/javadoc - classes/methods that should not be public
>
>
> 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 4/30/01 at http://www.devahelp.com or info -at- devahelp -dot- com

Sponsored by DigiPub Solutions Corp, producers of PDF 2001 Conference East, 
June 4-6, Baltimore, MD. Now covering Acrobat 5. Early registration deadline 
April 27. http://www.pdfconference.com. 

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