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.
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?
3. Should MathJax also be used in the User Guide?
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.
Thanks!
-Matt Adereth
http://adereth.github.io
