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 15:58:25 GMT
On 31 August 2012 16:51, Sébastien Brisard <sebastien.brisard@m4x.org> wrote:
> 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...

That's my point about providing examples - there is no need to reach consensus.

If the example works, use it; if not don't.

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

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


Mime
View raw message