Return-Path:
X-Original-To: apmail-commons-dev-archive@www.apache.org
Delivered-To: apmail-commons-dev-archive@www.apache.org
Received: from mail.apache.org (hermes.apache.org [140.211.11.3])
by minotaur.apache.org (Postfix) with SMTP id A2298D37B
for ;
Fri, 31 Aug 2012 13:52:40 +0000 (UTC)
Received: (qmail 45753 invoked by uid 500); 31 Aug 2012 13:52:40 -0000
Delivered-To: apmail-commons-dev-archive@commons.apache.org
Received: (qmail 45652 invoked by uid 500); 31 Aug 2012 13:52:40 -0000
Mailing-List: contact dev-help@commons.apache.org; run by ezmlm
Precedence: bulk
List-Help:
List-Unsubscribe:
List-Post:
List-Id:
Reply-To: "Commons Developers List"
Delivered-To: mailing list dev@commons.apache.org
Received: (qmail 45642 invoked by uid 99); 31 Aug 2012 13:52:40 -0000
Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230)
by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 31 Aug 2012 13:52:40 +0000
X-ASF-Spam-Status: No, hits=-2.3 required=5.0
tests=RCVD_IN_DNSWL_MED,SPF_HELO_PASS,SPF_PASS
X-Spam-Check-By: apache.org
Received-SPF: pass (nike.apache.org: domain of
SRS0=XiAc=G7=m4x.org=sebastien.brisard@bounces.m4x.org designates
129.104.30.34 as permitted sender)
Received: from [129.104.30.34] (HELO mx1.polytechnique.org) (129.104.30.34)
by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 31 Aug 2012 13:52:33 +0000
Received: from mail-ob0-f171.google.com (mail-ob0-f171.google.com
[209.85.214.171])
(using TLSv1 with cipher RC4-SHA (128/128 bits))
(No client certificate requested)
by ssl.polytechnique.org (Postfix) with ESMTPSA id E4F80140000B5
for ; Fri, 31 Aug 2012 15:52:11 +0200 (CEST)
Received: by obqv19 with SMTP id v19so7934162obq.30
for ; Fri, 31 Aug 2012 06:52:10 -0700 (PDT)
MIME-Version: 1.0
Received: by 10.60.12.42 with SMTP id v10mr1950709oeb.131.1346421130651; Fri,
31 Aug 2012 06:52:10 -0700 (PDT)
Received: by 10.60.144.66 with HTTP; Fri, 31 Aug 2012 06:52:10 -0700 (PDT)
In-Reply-To: <20120831124919.GM24856@dusk.harfang.homelinux.org>
References: <20120831031216.E0A7F23888E4@eris.apache.org>
<20120831124919.GM24856@dusk.harfang.homelinux.org>
Date: Fri, 31 Aug 2012 15:52:10 +0200
Message-ID:
Subject: Re: [Math] Formatting (Was: svn commit: r1379270 -
/commons/proper/math/trunk/...)
From: =?ISO-8859-1?Q?S=E9bastien_Brisard?=
To: Commons Developers List
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable
X-AV-Checked: ClamAV using ClamSMTP at svoboda.polytechnique.org (Fri Aug 31
15:52:12 2012 +0200 (CEST))
X-Org-Mail: sebastien.brisard.1997@polytechnique.org
X-Old-Spam-Flag: No, tests=bogofilter, spamicity=0.000000,
queueID=43689144C7CEE
Hi Gilles,
2012/8/31 Gilles Sadowski :
> Hello S=E9bastien.
>
>> Author: celestin
>> Date: Fri Aug 31 03:12:16 2012
>> New Revision: 1379270
>>
>> URL: http://svn.apache.org/viewvc?rev=3D1379270&view=3Drev
>> Log:
>> MATH-849: changed boundary case x =3D 8.0 in double Gamma.logGamma(doubl=
e).
>>
>> Modified:
>> commons/proper/math/trunk/src/main/java/org/apache/commons/math3/spe=
cial/Gamma.java
>>
>> Modified: commons/proper/math/trunk/src/main/java/org/apache/commons/mat=
h3/special/Gamma.java
>> URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/jav=
a/org/apache/commons/math3/special/Gamma.java?rev=3D1379270&r1=3D1379269&r2=
=3D1379270&view=3Ddiff
>> =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D
>> --- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/spe=
cial/Gamma.java (original)
>> +++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/spe=
cial/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.
>> *
>> *
>> - * For x < 8, the implementation is based on the double precisio=
n
>> + * For x ≤ 8, the implementation is based on the double precisio=
n
>
> My personal taste would be to write this as
> ---
> {@code x <=3D 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 p=
art
> of "{@code x <=3D 8}".]
>
> So, if nobody disagrees, this could become a formatting rule. [The ration=
ale
> (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 fo=
rm,
> 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 (
,
, , ... 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 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.
Thanks for this suggestion,
S=E9bastien
>
> Best regards,
> Gilles
>
>> * implementation in the NSWC Library of Mathematics Subroutine=
s,
>> - * {@code DGAMLN}. For x ≥ 8, the implementation is based on
>> + * {@code DGAMLN}. For x > 8, the implementation is based on
>> *
>> *