Re JDBC documentation, we must indicate which methods we support and which limitations there are. JDK source comments assume the method is supported whereas ours throw a NOT_IMPLEMENTED exception. Also there is the question of support for JDBC2 from JDK 1.1.X which I have addressed to some extent, and also the particular behaviour of HSQLDB wrt PreparedStatement methods, e.g. setObject methods when used with a column of the type OTHER.
Javadocs are for developers but the public JDBC methods are for developers who just use HSQLDB which means our users. Re renaming Channel and Access, a good idea, may just do it in this version. Regarding the URL you will find them already documented in our JDBC documentation, so if we concentrate there we can improve the documentation. As for your other suggestions, they are good ideas. If you prefer, you can do that documentation instead. Someone should take up the JDBC stuff, anyway. Any volunteers? Fred Toussi ----- Original Message ----- From: "Campbell Boucher-Burnet" <[EMAIL PROTECTED]> To: "fredt" <[EMAIL PROTECTED]>; <[EMAIL PROTECTED]> Sent: Saturday, March 30, 2002 9:11 AM Subject: Re: [Hsqldb-developers] JavaDoc Comments > 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 leav es > 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 _______________________________________________ hsqldb-developers mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/hsqldb-developers
