commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Phil Steitz" <>
Subject RE: cvs commit: jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment
Date Fri, 02 Jul 2004 17:20:52 GMT
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?

	-----Original Message----- 
	From: Mark R. Diggory [] 
	Sent: Fri 7/2/2004 8:51 AM 
	To: Jakarta Commons Developers List 
	Subject: Re: cvs commit: jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment

	What if we maintained "Citation Numbers" in the javadoc and then
	maintained references to external sources in the Math Site documentation?
	Al Chou wrote:
	>--- wrote:
	>>psteitz     2004/07/01 22:29:14
	>>  Modified:    math/src/java/org/apache/commons/math/stat/univariate/moment
	>>  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?
	>Albert Davidson Chou
	>    Get answers to Mac questions at .
	>To unsubscribe, e-mail:
	>For additional commands, e-mail:

View raw message