On 31 August 2012 16:51, Sébastien Brisard <sebastien.bris...@m4x.org> wrote:
> Hi sebb,
>
> 2012/8/31 sebb <seb...@gmail.com>:
>> On 31 August 2012 14:52, Sébastien Brisard <sebastien.bris...@m4x.org> wrote:
>>> Hi Gilles,
>>>
>>> 2012/8/31 Gilles Sadowski <gil...@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 Γ(x) for x > 0.
>>>>> * </p>
>>>>> * <p>
>>>>> - * For x < 8, the implementation is based on the double precision
>>>>> + * For x ≤ 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 < 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 / Γ(1 + x) - 1 for -0.5 ≤ x ≤
>>> 1.5. In case you wondered, . 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 ≥ 8, the implementation is based on
>>>>> + * {@code DGAMLN}. For x > 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-unsubscr...@commons.apache.org
>>>> For additional commands, e-mail: dev-h...@commons.apache.org
>>>>
>>>
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
>>> For additional commands, e-mail: dev-h...@commons.apache.org
>>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
>> For additional commands, e-mail: dev-h...@commons.apache.org
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
> For additional commands, e-mail: dev-h...@commons.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
