On Mon, 30 Dec 2019, 02:23 Gilles Sadowski, <gillese...@gmail.com> wrote:
> Hi.
>
> Le dim. 29 déc. 2019 à 23:25, Alex Herbert <alex.d.herb...@gmail.com> a
> écrit :
> >
> > I’ve dropped the static equals methods and reciprocal and pushed the
> updated class with MathJax.
> >
> > I put MathJax in whenever possible. This may be a bit too much. The
> rendered javadoc looks good but the javadoc rendered by my IDE without
> MathJax support can be very unreadable.
>
> One cannot have one's cake and eat it too.
>
> >
> > Have a look at the built javadocs and through an IDE and let me know
> your opinions on the current usage.
>
> I think that it's fine, when looking with a pager.
> I don't use an IDE. :-}
>
> >
> > It may be better to drop some use of MathJax such as \( z \) for {@code
> z} which would make the code more readable in an IDE when programming.
>
> Sure. [I seem to recall having mentioned that such usage of {@code} was
> fine.]
>
> > I’ve not explicitly laid out the latex equations for unparsed
> readability so some improvements could be made. However some equations are
> multi-line which gets wrapped to a single line if pure HTML without
> MathJax. For example see atanh and acos. I do not know how to lay this out
> to make it readable without MathJax.
>
> No need IMO.
>
> > So perhaps a note in the class javadoc that the use of MathJax is
> required to read the formatted equations.
>
> This a general comment (i.e. valid for all classes in this component).
> But isn't MathJax active (when browsing the "Commons" site?
>
Yes. I think I'll have another look over it. Maybe separate all the
equations into their own paragraphs. Thus if they don't render they will be
easy to ignore.
I think small latex inline is still readable so I'll leave it as the
rendered javadoc is nicer.
> > On another c++ note the documentation for the C99 functions on C++
> reference lists the special return values, e.g. [1]. This is similar to the
> special return values listed in java.util.Math for functions, e.g. [2]. I
> think it would be good to add these to the javadoc. It should be a simple
> cut and reformat from the ISO C99 Annex G that the class has been tested
> against.
>
> How about including a link to the respective C++ doc pages?
>
I considered that. But having to jump about between websites to get the
information is not user friendly. I'll try out adding them to the javadoc.
It should just be about 10 list elements per C99 method so it's not that
much.
> Regards,
> Gilles
>
> >
> > [1] https://en.cppreference.com/w/c/numeric/complex/cacos <
> https://en.cppreference.com/w/c/numeric/complex/cacos>
> > [2]
> https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#atan2-double-double-
> <
> https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#atan2-double-double-
> >
> >
> > Alex
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
> For additional commands, e-mail: dev-h...@commons.apache.org
>
>
