commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <p...@steitz.com>
Subject Re: [math] Design review pre 1.0
Date Sat, 15 May 2004 03:25:26 GMT
Tim O'Brien wrote:
> 
>>-----Original Message-----
>>From: Stephen Colebourne [mailto:scolebourne@btopenworld.com]
>>3) Javadocs are sometimes thin. On occasions, they are written as
>>paragraphs
>>visually but without the HTML <p> tag. (eg. UnivariateRealSolver) or
>>missing, eg StandardDeviation
> 
> [Tim O'Brien] 
> 
> Agree, JavaDocs are somewhat thin and in some cases we just reference some
> other web site.   (i.e. ComplexMath simply has a URL:
> http://myweb.lmu.edu/dmsmith/ZMLIB.pdf ).  A good benchmark to use is
> Digester, our "users" should be able to use a commons component without
> needing to look at the source, and having fuller JavaDoc goes a long way
> towards this goal.

I agree that users should be able to effectively use any commons component 
without looking at the source and that means (among other things) in 
[math] we need to include or reference full definitions and algorithm 
descriptions for everything.  Given the nature of mathematical definitions 
(lots of dependencies :-), however, I do not think that it is feasible or 
desirable to include full definitions of everything embedded in the 
javadoc.  My HO is that a link to a (stable, authoritative) reference and 
sticking with standard terminology is better than trying to embed too much 
math in the javadoc.

+1 to opening tickets pointing to the "thin" or garbled stuff, though.

Phil
> 
> So, be warned, I'm using Bugzilla as a task list.
> 
> Tim
> 
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
> 



---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message