I think the JDBC documentation is already done in a way:  If we simply do
not include *any* javadoc comments for the JDBC interface methods, then if
the latest JDK src is on the javadoc classpath at javadocs build time, then
the comments are simply copied over from there, with an indication that such
has been done.  I think this behaviour of javadoc is much preferable to
exploit than requiring of ourselves to actually copy the javadoc comments
over from the java.sql.* interfaces as we have done in the past, since
rebuilding the docs against the latest jdk source has the nice effect of
synching any updates or corrections that may have occured to the JDK source
javadoc comments since last build of the javadocs, plus this approach leaves
our source files much less cluttered.

What do you think on this?

Based on these observations, do you really want to focus on the jdbc class
javadocs first?  After all,  the javadocs are for developers, really, and
most of them will already be quite familliar with the JDBC API.  Of course,
if you mean just the (package) private methods and member variables, then
fine...I agree this needs some work, and I am quite willing to do it

However, I was thinking that Channel, Access, User, Database, Parser,
Expression, Function, Log, Cache, and Index would be the prime targets, with
their ancilliary classes running a close second, since these are the classes
that new developers must understand as soon as possible in order to get up
to speed and start either auditing, debugging, improving, writing test cases
for, or extending the code base.

I was also thinking that perhaps a couple of class renames are in order.
For instance, I really think Channel would be much more appropriately named
Session, as that is really what it represents.  Similarly, I think Access
would be far more recognizable to new developers if named something like
UserManager, as that is basically what it does.  I could suggest some other
changes, but really those changes probably represent a matter of personal
preference, rather than an actual attempt to correct what I feel are
misleading, confusing, or at least rather opaque class name choices.

As far as user-level documentation is concerned, I would say the most often
asked questions are:

what is the hsqldb jdbc url specification and it's exact semantics/where is
the database actually created, based on the url/what are the command line
options to xxx... and what do they mean?
does hsqldb support the sql xxx syntax/how do you do xxx in sql on hsqldb?

>From these observations, I think the highest priorities for user-level
documentation are:

A really well written, high-profile (e.g. under the sf docs link, rather
than as a link off the home page) "Getting Started With HSQLDB"
A much less terse hsqldb SQL SYNTAX section, also in a prominent place (so
we don't have to keep answering posts with simple redirects to either
download the distribution or navigate to the home page)
A condensed (Cole's Notes, if you will) section, containg the command line
options and their meanings, for all classes with main methods, such as
server, web server, DatabaseManager, Transfer, etc.

To be honest, if we concentrated on just these three things w.r.t.
user-level docs, I don't see why it should take us more than a couple of
days to get something quite acceptable out there.

----- Original Message -----
From: "fredt" <[EMAIL PROTECTED]>
Sent: Friday, March 29, 2002 10:12 AM
Subject: Re: [Hsqldb-developers] JavaDoc Comments

> Thanks, nothing has yet been assigned. The highest priority, I suppose, is
> the JDBC documentation, as it is aimed at the user.  You can do these if
> wish.
> Fred
> ----- Original Message -----
> From: "Campbell Boucher-Burnet" <[EMAIL PROTECTED]>
> To: "Fred Toussi" <[EMAIL PROTECTED]>;
> Sent: 29 March 2002 02:57
> Subject: Re: [Hsqldb-developers] JavaDoc Comments
> Just let me know which files are laready taken, which have the highest
> priority, and I'll spend some time each day on the one's I am assigend,
> sending the results to you each night...
> ----- Original Message -----
> From: "Fred Toussi" <[EMAIL PROTECTED]>
> Sent: Thursday, March 28, 2002 2:07 PM
> Subject: [Hsqldb-developers] JavaDoc Comments
> > There are a large number of warnings reported by ant javadoc for 1.7.0
> RC3.
> > Quite a lot of these are simply caused by missing descriptions to
> parameter
> > tags. Note that the source has been through some automatic javadoc
> creation
> > reformatting, so some of the comments that look correct, are in fact
> > misleading. Volunteers are needed to update the javadoc comments in the
> > source. Contributions can be as basic as fixing the technicalities or as
> > complex as you want--perhaps you can give a give a better insight into
> what
> > each method does. If you think we can remove the javadoc comments for
> > methods that are obvious, let us know.
> >
> > We need to fix things as we move forward. So here is an opportunity to
> > contribute.
> >
> > Fred Tosusi
> >
> >
> > _______________________________________________
> > hsqldb-developers mailing list
> >
> >
> _______________________________________________
> hsqldb-developers mailing list
> _______________________________________________
> hsqldb-developers mailing list

hsqldb-developers mailing list

Reply via email to