commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From robert burrell donkin <robertburrelldon...@blueyonder.co.uk>
Subject Re: [math][patch] Lets try this again, here's a new patch for Rolling
Date Fri, 16 May 2003 15:54:12 GMT
On Thursday, May 15, 2003, at 10:34 PM, Phil Steitz wrote:
> Phil Steitz wrote:

<snip>

>>> maybe we could come up with a standard format for the class comments.
>> I am struggling a bit on this. Here are some questions:
>> 1. I think it would be best to reference external documentation for all
>>    definitions and standard computational formulas.  This obviously
>>    creates dependencies and the need to maintain links.  Is this
>>    OK?  Here is a good reference for basic stat definitions:
>>    http://rd11.web.cern.ch/RD11/rkb/titleA.html.  If this is acceptable,
>>    I will include references to the definitions there throughout.  We
>>    will need to find similar sources for documentation of numerical
>>    algorithms.

that sounds pretty good.

in the long term, i worry a little about broken links. maybe (in the 
medium term) we could make the javadocs link to the component 
documentation hosted at jakarta and this contain link or links to these 
source but this sounds like a good start.

>> 2. The math/stat packages that I like the most (S-Plus, SAS) maintain
>>    Users' and Programmers' Guides with detailed information on
>>    algorithms and implementation details.  I am not sure that putting
>>    all of the implementation documentation in the javadoc will be
>>    convenient either for the developers or the users.  I would suggest
>>    the following principles:
>>       * favor standard algorithms with external documentation and
>>         document these using external references wherever possible
>>       * document simple extensions/implementation notes in javadoc

+1

>>       * maintain a separate user's guide including more extensive
>>         implementation notes, performance analysis, etc.

the javadocs are are easy to maintain and version, and are distributed 
with each binary release. unfortunately (at least in the open source world)
  user guides tend to be written late and developers have a tendency not to 
read user guides. many commons components has user guides that are 
integrated as part of the javadocs (usually as package documentation).

maybe we could maintain a systematic versioned user guide which is linked 
from the javadocs. this is probably something that should be raise again 
once the website is up.

>> 3. In many (most?) cases it will be most convenient to define the
>>    interface contracts and whatever implementation notes go in the
>>    javadocs in the method comments rather than the class
>>    comments
>> I will submit a simple example defining a chi-square test statistic 
>> using these ideas in a message to follow.
>
> http://issues.apache.org/bugzilla/show_bug.cgi?id=19971

looks good.

but maybe we could add an additional 'usage' section for implementation 
classes. for most classes, this would probably say something like 'general'
  but might contain stuff like 'not recommended for memory-limited 
applications'.

- robert


---------------------------------------------------------------------
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