Thanks Campbell, 1) I am not concerned at all about commenting 1.6.1 and 1.4.x, otherwise what's the point of doing all the work to get 1.7.0 out. As for the next release, we need a two-version (fat and slim) distribution because of the very large size of your much improved metadata. (To put this in context, the JAR for the JDBC2 driver for one of the major RDBM's is over 500K in size, and that is just the JDBC driver, not the engine). So basically the new stuff will be a new driver, with its own documentation. The RC4 stuff (yes, it will be over the pond RSN) needs the documentation updates I discussed and there are improvements in setObject() functionality. Obviously both the big MetaData and small MetaData stuff share what is not MetaData related.
2) Sure, why not write something up and that will fit in with the stuff Mike is working on. Sometimes it's better to get it done first and discuss later. 3) My view of javadocs priorities is as I said before, JDBC first. Fred ----- Original Message ----- From: "Campbell Boucher-Burnet" <[EMAIL PROTECTED]> To: "Fred Toussi" <[EMAIL PROTECTED]>; <[EMAIL PROTECTED]> Sent: Saturday, March 30, 2002 9:38 PM Subject: Re: [Hsqldb-developers] JavaDoc Comments > 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
