Fred: 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 hsqldb.org home page) "Getting Started With HSQLDB" section 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 hsqldb.org 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]> To: <[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 you > wish. > > Fred > ----- Original Message ----- > From: "Campbell Boucher-Burnet" <[EMAIL PROTECTED]> > To: "Fred Toussi" <[EMAIL PROTECTED]>; > <[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]> > To: <[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 > > [EMAIL PROTECTED] > > https://lists.sourceforge.net/lists/listinfo/hsqldb-developers > > > > > > _______________________________________________ > hsqldb-developers mailing list > [EMAIL PROTECTED] > https://lists.sourceforge.net/lists/listinfo/hsqldb-developers > > > _______________________________________________ > hsqldb-developers mailing list > [EMAIL PROTECTED] > https://lists.sourceforge.net/lists/listinfo/hsqldb-developers > _______________________________________________ hsqldb-developers mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/hsqldb-developers
