Hello, For small scale components, like a FooUtils or any class that can be used in a standalone manner, I have found *extremely* useful to have nice Javadoc comments with *code examples*. I would like to encourage all contributors to keep this in mind.
This type of stuff also depends on your philosophical approach to unit testing vs Javadoc'ing. I've read things like: The unit test should be consulted for usage and examples. For me this does not quite cut it. Gary -----Original Message----- From: robert burrell donkin [mailto:[EMAIL PROTECTED] Sent: Thursday, July 17, 2003 13:47 To: Jakarta Commons Developers List Subject: Re: [release docs] some thoughts i'd like to encourage people to submit comments and improvements ASAP. i will move things around soonish so that these are linked at the main how-to-release documents. On Tuesday, July 15, 2003, at 12:56 AM, Henri Yandell wrote: > Couple of thoughts on Robert's release documentation at: > > http://jakarta.apache.org/commons/releases/ > > In prepare.html, the manifest description doesn't quite match Sun's. They > don't mention 'Extension-Name' this is to do with the java extension mechanism but i forget now exactly why it's in there. tradition, quite probably. i've done a quick search and the best link i can find it http://marc.theaimsgroup.com/?l=jakarta-commons-dev&m=101804864505521&w=2. > and they say to include the Manifest version. yep. missed that out. > In release.html, it has the builder building the release version in > their own sandbox. I would recommend that instead it suggest the builder > checkout the particular tag into their new working directory and perform > the build there. that's what i do. probably didn't make that clear > The entire source tree does not always want to go into > the build. the entire source tree shouldn't go into the build. but what goes into the build should be controlled by the build process, shouldn't it? (or maybe i'm a little confused.) > Then after the binaries have been built, I would recommend > releasing and re-checking out to create the sources. the new follow's craig original quite closely for the source build. it says create a temporary directory and then export (rather than checkout) the source. is this what you mean? > Also, a -q on the zip -r will be appreciated by the builder :) i like it noisey ;) want to volunteer to patch these documents? - robert --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
