I would prefer to keep the references that we actually need in the javadoc itself.
The ones that I removed were just references to (standard, straightforward)
definitions, which I had added inline. In general, I want to include definitions in
the javadoc unless this is not tractable (too many dependent concepts, formulas too
complex, etc.), in which case a reference to a definitive source should be included.
When we use algorithms that are not elementary or widely known, we should include
references to docs or papers (e.g. the Chan et al references for the moment updating
formulas).
Unfortunately, the first sentence above is a PITA to maintain and leaves us open to
broken links (last time I rank linkcheck, the p-value reference was broken :-( That
makes suggestions like Mark's appealing, but I don't like losing the hyperlinks. Is
it excessively brittle to include links from the javadoc back to the user guide? If
so, is there any stable place (better than ~psteitz) where I can host some definitions?
Phil
-----Original Message-----
From: Mark R. Diggory [mailto:[EMAIL PROTECTED]
Sent: Fri 7/2/2004 8:51 AM
To: Jakarta Commons Developers List
Cc:
Subject: Re: cvs commit:
jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment
Kurtosis.java Skewness.java
What if we maintained "Citation Numbers" in the javadoc and then
maintained references to external sources in the Math Site documentation?
Al Chou wrote:
>--- [EMAIL PROTECTED] wrote:
>
>
>>psteitz 2004/07/01 22:29:14
>>
>> Modified: math/src/java/org/apache/commons/math/stat/univariate/moment
>> Kurtosis.java Skewness.java
>> Log:
>> Removed link to external definition, as formula has been added to javadoc.
>>
>>
>
>Maybe it's my grad school experiences talking, but I would prefer to retain
>links to external references. That way if a user (or even one of us
>developers) ever needs to look up the original references, its easy to do, and
>there's an explicit statement of which source of information we used, rather
>than doing a Web search and wondering which (if any) of the resulting
resources
>was the original reference. Maybe that doesn't matter to anyone but me?
>
>
>Al
>
>=====
>Albert Davidson Chou
>
> Get answers to Mac questions at http://www.Mac-Mgrs.org/ .
>
>---------------------------------------------------------------------
>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]
