[
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
