commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <>
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 []
>>3) Javadocs are sometimes thin. On occasions, they are written as
>>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:
> ).  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.

> So, be warned, I'm using Bugzilla as a task list.
> Tim
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message