Writing JavaDoc - Please Advise

Subject: Writing JavaDoc - Please Advise
From: Kevin Cheek <cheek1 -at- sbcglobal -dot- net>
To: TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 29 Aug 2003 13:18:00 -0700 (PDT)


I am now at a genuinely neat startup. My main task right now is to
write the JavaDoc comments in their API.

Now, they already have the standard JavaDoc kind of comments (such as
for createUser: /** Creates a new user. @param uName User Name,
etc.*/). I want to make the JavaDoc truly useful for a developer
faced with this API for the first time. Can any of you give some
advice about the types of information that I can include here? Have
you seen (or written) some examples of some exemplary JavaDoc?

A little more info: the first series of APIs that need documenting
are a set of interfaces and a factory class that provide a facade for
a bunch of entity bean classes. The whole thing applies to managing
an app server. Only the interface classes and the one factory class
are going to be visible to the customer.

Any help, pointers, examples, and not-too-derisive comments are


Kevin Cheek
cheek1 -at- sbcglobal -dot- net

PS. Please, no debates about JavaDoc versus real programmer's guides
and references. The task has been assigned.

Previous by Author: Re: Visio-FM-help
Next by Author: RE: How does Microsoft create the help files for Microsoft Word?
Previous by Thread: Re: Visual Basic Tutorial
Next by Thread: insert a temperature degree symbol

What this post helpful? Share it with friends and colleagues:

Sponsored Ads