commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sébastien Brisard <sebastien.bris...@m4x.org>
Subject Re: [Math] Formatting (Was: svn commit: r1379270 - /commons/proper/math/trunk/...)
Date Fri, 31 Aug 2012 15:51:19 GMT
Hi sebb,

2012/8/31 sebb <sebbaz@gmail.com>:
> 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".
>
Yes, we do not want to frighten anyone. However, the aim of this
document is to pick the rules (whatever you call them) we feel are
REALLY important to improve the quality and consistency of the source.
>
> 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.
>
Please have a look at MATH-852. I have already written one example for
another "rule". I agree with you: examples do help.

>
> Such examples should prove useful across all Commons components.
>
One step at a time! I know it's going to be difficult to reach
consensus within CM. So maybe we should wait until our document is
fairly stable. Then we can submit it to anyone to discuss...

Sébastien

>> 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
>


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


Mime
View raw message