Hello.
On Sat, 26 Oct 2013 20:02:14 -0400, Matt Adereth wrote:
I recently wrote JavaDocs for a class I was adding to Commons Math
and I
tried to adhere to this requirement:
External references or full statements of definitions for all
mathematical terms used in component documentation must be provided.
I wanted to make my documentation appear consistent with the rest of
the
JavaDocs, but I found that formulas were written using multiple
conventions. Sometimes it would be plain text with tags for sub and
superscript and sometimes it would be inside {@code} blocks. Other
inconsistencies include "sum" written out vs. ∑ vs. Σ and "abs(x)"
vs.
"|x|".
I had the idea to add MathJax support, but I was happy to find that
it had
already been added in MATH-1006 and that the updated developer
documentation will encourage its use.
I'm left with a few questions:
1. Are there any thoughts about doing a pass through all the JavaDocs
and
updating the formulas to consistently use LaTeX? This would be
something
I'm interested in doing to improve the usability and appearance of
the
documentation.
Your help is certainly welcome. Thanks.
I totally agree that uniformity is a quality to be sought in
documentation.
If you intend to work on this, please open a ticket on the
bug-tracking system.
I'd suggest to create (at least) one patch per Java file where
the Javadoc is upgraded.
2. If there were a full pass, it might be a good opportunity to make
the
documentation consistent in other ways, such as consistent reference
styles
for bibliographies and links to MathWorld or Wikipedia. Are there
any
other sweeping changes you would like to see?
Could you please report here the different "styles" (or lack
thereof) used for references? We should collect input and then
decide about the style to be adopted.
3. Should MathJax also be used in the User Guide?
I think so.
4. What changed after Luc Maisonobe's comment on MATH-581 (
https://issues.apache.org/jira/browse/MATH-581?focusedCommentId=13054851)
that made it ok to start depending on MathJax? I'd hate to do work
on this
only to have the MathJax dependency removed.
I understand your concern. I sure hope that this won't
happen.
The dependency is through a maven plugin, specified in
the project's "pom.xml". This move was done fairly recently
and nobody opposed it.
I don't know whether it is now necessary to be connected to
the Internet in order to be able to visualize the formulae,
nor whether it is still a problem if it were the case...
Best regards,
Gilles
Thanks!
-Matt Adereth
http://adereth.github.io
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
