-----Original Message----- From: Stephen Colebourne [mailto:[EMAIL PROTECTED] 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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
