commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <>
Subject [math] documentation principles
Date Fri, 16 May 2003 18:00:50 GMT
--- robert burrell donkin
<> wrote:
> 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:
> >> 
> If this is acceptable,
> >>    I will include references to the definitions
> there throughout.  
After researching this some more as I prepare my
RandomData generation stuff for submission, I don't
think it will work to settle on a "canonical source"
for either stat or math, even for the basic
definitions. We will need to reference multiple
sources. We will also want to carefully review the
references used in submissions (and sometimes argue
about what the "right" definitions are :-) 

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

We can look into this as we get further along.  For
now, I assume it is OK to add links to external
sources as appropriate in the javadoc. 
> >> 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. 
The good ones e.g. tomcat, struts) really are *very*
useful and lots of people do read them.  You can also
refer people to the guides when they ask questions.
>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.

Here again, something to think about as we get further
along. One last point before letting this drop (for
now).  Mathematical documentation in HTML is painful,
trying to embed it in javadoc is cruel and unusual
punishment. This is another reason to externalize the
user's guide.  The eventual user's guide will need to
include images and/or possibly be distributed as pdf,
tex, or postcript.  Probably should not have just
opened up that can of worms...Something to think about
down the road.
> >> 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.
> >
> >
> 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'.

Yes. The way I am thinking about this now is that the
documentation for implementation classes/methods may
contain the following optional elements:

Numerical Considerations -- includes things like
possible loss of precision/how errors propagate,
behaviour of implementation algorithms in boundary
situations, etc. Only necessary when there is
something that the user should know.

Usage Notes -- includes things like memory
requirements, JDK differences, performance
considerations.  Again, only necessary when there is
something that the user should know.

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

Do you Yahoo!?
The New Yahoo! Search - Faster. Easier. Bingo.

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

View raw message