Mailing-List: contact issues-help@commons.apache.org; run by ezmlm
Precedence: bulk
Reply-To: issues@commons.apache.org
Date: Tue, 22 Feb 2011 14:30:38 +0000 (UTC)
From: "Gilles (JIRA)" <jira@apache.org>
To: issues@commons.apache.org
Message-ID: 
 <1874030729.8248.1298385038462.JavaMail.tomcat@hel.zones.apache.org>
In-Reply-To: 
 <675742887.6828.1298328759734.JavaMail.tomcat@hel.zones.apache.org>
Subject: [jira] Commented: (MATH-521) Changes in
 "HarmonicCoefficientsGuesser"
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 7bit


    [ https://issues.apache.org/jira/browse/MATH-521?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12997815#comment-12997815 ] 

Gilles commented on MATH-521:
-----------------------------

Why the remark about GPL? This is not a code contribution.

Obviously, to render a LaTeX source, you need a LaTeX installation!

I hope that you don't consider this requirement as a "dependency": The CM code will not need "latex" to run...
Neither are "latex" and "dvipng" needed to read the Javadoc; they are needed only on the machine that builds the documentation. It's not even a mandatory requirement: "javadoc" can generate the doc without the taglet: It will display warnings and just not render the "unknown" tags.

This tool is about as easy as can be; hence this option is quite worth investigating further, especially since CM also aims at high-quality documentation. In the scientific domain, this goes together with LaTeX formatting.

We can have a documentation-writing rule stating that the possibility of LaTeX formatting should not be abused: For example, that the standard tags ("@param", "@return", "@throws", etc.) should not use it, but that it can be used to avoid the kind of unreadable documentation we have in this class.


> Changes in "HarmonicCoefficientsGuesser"
> ----------------------------------------
>
>                 Key: MATH-521
>                 URL: https://issues.apache.org/jira/browse/MATH-521
>             Project: Commons Math
>          Issue Type: Improvement
>            Reporter: Gilles
>            Assignee: Gilles
>            Priority: Minor
>              Labels: api-change, documentation
>             Fix For: 3.0
>
>         Attachments: example_LaTeXLet.tar.gz
>
>
> (1) The "guess" method throws "OptimizationException" when the algorithm fails to determine valid values for amplitude and angular frequency.
> There are no test showing how such a situation can occur.
> Moreover, since this procedure is used to provide an initial guess to an optimizer, it is better to pick any values for those parameters (e.g. zero) and let the optimizer proceed from that initial point.
> (2) The class javadoc seems very thorough in explaining the algorithm, but is quite unreadable in the source code, making it fairly useless for checking how the code complies with the comments. I think that this explanation should go in the user guide (and leave a mostly "plain text" outline of the algorithm, referring to the guide for details). [Does the format of the user guide allow such tricky (ASCII "art") constructs?]

-- 
This message is automatically generated by JIRA.
-
For more information on JIRA, see: http://www.atlassian.com/software/jira