1.) Ok. Thanks for the clarifications. I'm still 100% clear though, because I forgot to ask some questions:
When we add in my MetaData stuff, much of the current javadoc for JDBC will cease to be valid. So, should I be docing based on the next release including the MetaData patches, or should I be docing in such a way that we can also apply the doc updates to 1.6.1 and 1.4.x quite easily (since not *too* much is different really, except a couple of bug fixes and support for client-side scrolling)? 2.) w.r.t. a quick-start guide, separate from the main body of user (vs javadoc) documentation: I was thinking something more along the lines of a 1-2 pager with all of the really important stuff for getting "immediate gratification" condensed and posted under the hsqldb sf docs section. For an example, see: http://jxdbcon.sourceforge.net/docs/minitut.html Obviously, our info is different, but I think the concept is valid. I always find I have much more incentive to go read the larger body of documentation once I have a core set of facts that I can use to start getting some results. The guickstart referenced above, Keve was nice enough to post was in response to my requests/suggestions back in July, 2001 at http://sourceforge.net/forum/forum.php?thread_id=123205&forum_id=81298. So, what do you think about the idea of doing something similar and posting it under our source forge Docs section? 3.) Given the above, and the previous conversation thread, could you give me a priority ordered list of the classes you would like me to update with better javadoc comments? As soon as I get the list, I will start. ----- Original Message ----- From: "Fred Toussi" <[EMAIL PROTECTED]> To: <[EMAIL PROTECTED]> Sent: Saturday, March 30, 2002 5:26 AM Subject: Re: [Hsqldb-developers] JavaDoc Comments > 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 > _______________________________________________ hsqldb-developers mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/hsqldb-developers
