commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <seb...@gmail.com>
Subject Re: [Math] Formatting (Was: svn commit: r1379270 - /commons/proper/math/trunk/...)
Date Fri, 31 Aug 2012 14:24:48 GMT
On 31 August 2012 14:52, Sébastien Brisard <sebastien.brisard@m4x.org> wrote:
> Hi Gilles,
>
> 2012/8/31 Gilles Sadowski <gilles@harfang.homelinux.org>:
>> Hello Sébastien.
>>
>>> Author: celestin
>>> Date: Fri Aug 31 03:12:16 2012
>>> New Revision: 1379270
>>>
>>> URL: http://svn.apache.org/viewvc?rev=1379270&view=rev
>>> Log:
>>> MATH-849: changed boundary case x = 8.0 in double Gamma.logGamma(double).
>>>
>>> Modified:
>>>     commons/proper/math/trunk/src/main/java/org/apache/commons/math3/special/Gamma.java
>>>
>>> Modified: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/special/Gamma.java
>>> URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/special/Gamma.java?rev=1379270&r1=1379269&r2=1379270&view=diff
>>> ==============================================================================
>>> --- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/special/Gamma.java
(original)
>>> +++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/special/Gamma.java
Fri Aug 31 03:12:16 2012
>>> @@ -222,9 +222,9 @@ public class Gamma {
>>>       * Returns the value of log&nbsp;&Gamma;(x) for x&nbsp;&gt;&nbsp;0.
>>>       * </p>
>>>       * <p>
>>> -     * For x &lt; 8, the implementation is based on the double precision
>>> +     * For x &le; 8, the implementation is based on the double precision
>>
>> My personal taste would be to write this as
>> ---
>>  {@code x <= 8}
>> ---
>> [As I'm not an HTML parser,
>>
> I'm a bit disappointed by your poor parsing capabilities ;-)
>
>> it always takes me a few moments to figure out a
>> sequence such as "x &lt; 8", while it is easier to focus on the central part
>> of "{@code x <= 8}".]
>>
>> So, if nobody disagrees, this could become a formatting rule. [The rationale
>> (to be included in the document you proposed to create) would be that
>> Javadoc comments should be as easy as possible to read in their source form,
>> for the developer's sake.]
>>
> Yeah, and it gets worse when I had to find a work around for the
> decimal point not being interpreted as the end of the first sentence:
> I ended up with something like
> Returns the value of 1 / &Gamma;(1 + x) - 1 for -0&#46;5 &le; x &le;
> 1&#46;5. In case you wondered, &#46; is simply '.'. This is uggly, I
> agree.
>
> I was thinking this very morning of something like "HTML tags are
> allowed as long as reading the source file is still reasonably easy".
> I'm quite happy with a more radical approach, like "HTML text
> formatting tags should be avoided as much as possible. Paragraph
> formatting (<p>, <li>, <pre>, ... is allowed)". Note that it has not
> been applied consistently in CM yet : in some parts, formulae are
> formatted with HTML tags, in other parts, it's pure {@code }. I
> contributed to this mess :-(
> As sebb mentions {@code } prevents *any* formatting, but this would
> not really be an issue. If needed, we can use <pre></pre> tags and
> nice text-based equations (again, tools like Maxima can help a lot),
> even if it looks old fashioned.
>
> I'll write something up in the JIRA ticket, so that everyone can review it.

Rather than formal rules, maybe it would be better to treat such
formatting ideas as "best practice".

That is, provide examples of different ways to document certain tricky
constructs.
This should make it more obvious when to choose a particular method.
And equally, it would show when there is no particular best choice.

Such examples should prove useful across all Commons components.

> Thanks for this suggestion,
>
> Sébastien
>>
>> Best regards,
>> Gilles
>>
>>>       * implementation in the <em>NSWC Library of Mathematics Subroutines</em>,
>>> -     * {@code DGAMLN}. For x &ge; 8, the implementation is based on
>>> +     * {@code DGAMLN}. For x &gt; 8, the implementation is based on
>>>       * </p>
>>>       * <ul>
>>>       * <li><a href="http://mathworld.wolfram.com/GammaFunction.html">Gamma
>>> @@ -249,7 +249,7 @@ public class Gamma {
>>>              return logGamma1p(x) - FastMath.log(x);
>>>          } else if (x <= 2.5) {
>>>              return logGamma1p((x - 0.5) - 0.5);
>>> -        } else if (x < 8.0) {
>>> +        } else if (x <= 8.0) {
>>>              final int n = (int) FastMath.floor(x - 1.5);
>>>              double prod = 1.0;
>>>              for (int i = 1; i <= n; i++) {
>>>
>>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>> For additional commands, e-mail: dev-help@commons.apache.org
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message