[
https://issues.apache.org/jira/browse/MATH-521?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12997775#comment-12997775
]
Gilles commented on MATH-521:
-----------------------------
{quote}
The javadoc is for sure not perfect but is readable [...]
{quote}
There should be a balance between "nice" graphics in a browser and readability
_within_ the source code.
In this particular case, it is more important that a developer can read the
algorithm description _in the source file_ because most users that will read
the API doc of that class rendered in a browser, will
# not call it directly, and
# be interested in how to use it, not how it works.
> 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
>
>
> (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
