james-server-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Andrew C. Oliver" <acoli...@apache.org>
Subject Re: about javadocs (was: Re: FW: What do we need to release 2.1?)
Date Mon, 19 Aug 2002 14:27:44 GMT
consider yourself upgraded in my book! ;-)

Danny Angus wrote:
>>or something as
>>fundamental as the correct documentation for how to setup a database URL
>>(which is correct in the CVS, and wrong in the current download).
> 
> 
> If this is the case it because the docs have been fixed.
> 
> And.. you should only consider the relevance of the stable "release"
> versions' documentation, the "latest" and "nightly" builds are strictly
> snapshots of work-in-progress, as such they should not be expected to
> function, nor should documentation be expected to be correct in any aspect.
> 
> Furthermore James has never released a Beta quality version yet, all the
> releases so far have, for various reasons, been considered to be Alpha
> quality code.
> 
> I subscribe to Andy's opinion that James is hard for a new user to get
> started with, because I have had to nursemaid many such users through their
> first experience with James.
> 
> In addition to documentation making life easier for users remember also that
> a +1 vote for a release binds the voter to support that release by
> participating on the developers and users lists. This is a great incentive
> to commiters to produce clear and accurate user documentation, and clear and
> accurate code documentation.
> 
> IMHO while the XP case for not documenting code is based in part upon the
> assumption that the code should be easy to follow and documentation  ca be
> used to avoid writing clear code, it does not follow that concise targeted
> code documentation obfuscates the code.
> 
> I rather believe that good javadoc documentation can encourage encapsulation
> and re-use by removing the necessity for programmers to concern themselves
> with the detail of code not directly relevant to the issues they are
> addressing, revealing method signatures and documenting their intended use
> cannot, surely, be counter productive, particularly in an OSS project.
> 
> Take a look at the Tomcat javadocs, they reveal the architecture of Tomcat
> in just enough detail for an outsider to extend and adapt the product,
> without explaining away bad practices, or forcing you to read the code
> itself.
> 
> I strongly believe that code documentation should be a halfway house between
> user documentation and the code itself, providing a convenient and easily
> navigable journey through the architecture, un-encumbered by the
> implementation details.
> 
> d.





--
To unsubscribe, e-mail:   <mailto:james-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:james-dev-help@jakarta.apache.org>


Mime
View raw message