Mailing-List: contact issues-help@commons.apache.org; run by ezmlm
Precedence: bulk
Reply-To: issues@commons.apache.org
Date: Tue, 18 Sep 2012 22:36:09 +1100 (NCT)
From: "Thomas Neidhart (JIRA)" <jira@apache.org>
To: issues@commons.apache.org
Message-ID: <1714714029.91851.1347968169405.JavaMail.jiratomcat@arcas>
In-Reply-To: <747443963.15054.1346297407573.JavaMail.jiratomcat@arcas>
Subject: [jira] [Commented] (MATH-852) Improvements to the Developer's Guide
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable


    [ https://issues.apache.org/jira/browse/MATH-852?page=3Dcom.atlassian.j=
ira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=3D134577=
51#comment-13457751 ]=20

Thomas Neidhart commented on MATH-852:
--------------------------------------

If the goal is to have proper formatted XHTML, than I am fine with this, an=
d we should have </p> tags as well.

@punctuation: I like the approach in the javadoc tutorial, that one line fr=
agments are not ended with a period whereas if there is an additional descr=
iption, they are separated by a period and the final sentence also ends wit=
h a period. Keep in mind that most @param descriptions are not really sente=
nces:

{noformat}
 * @param text1  the text of the tool tip
 * @param text1  the string to display.  If the text is null,=20
 *               the tool tip is turned off for this component.
{noformat}

@indentation: the rule is actually quite simply and derived from the need t=
o have readable javadoc in your IDE (in the browser it does not matter, as =
the javadoc tool formats it for you). When there are lots of @param, @throw=
s and a @return tag with long descriptions this can easily lead to a wall o=
f text that is very difficult to read. The indentation is there to easily s=
eparate the different tags with your eye. Whether you use 2 or more spaces =
depends what you prefer (I think the default formatter in eclipse puts a fi=
xed indentation at position 19/20).
               =20
> Improvements to the Developer's Guide
> -------------------------------------
>
>                 Key: MATH-852
>                 URL: https://issues.apache.org/jira/browse/MATH-852
>             Project: Commons Math
>          Issue Type: Improvement
>            Reporter: S=C3=A9bastien Brisard
>              Labels: formatting, guidelines
>
> Recent discussions (see MATH-851, as well as these threads [1|http://mark=
mail.org/thread/utxuipyolpnche5o], [2|http://markmail.org/thread/sma3nwa5j3=
hspvp5]) have shown that our actual requirements (especially regarding form=
atting) are higher than stated in the Developer's Guide. This leads to conf=
usion among new contributors, as well as recent committers. It is therefore=
 proposed to revise this guide, in order for it to reflect the actual expec=
tations regarding submitted code.
> This guide should however not act as a deterrent for new contributors, so=
 attention should be paid to "rules" we consider as essential vs. superfluo=
us rules.
> Here is an extract of the developer's guide in its current state
> h3. Coding Style
> Commons Math follows [Code Conventions for the Java Programming Language|=
http://www.oracle.com/technetwork/java/codeconv-138413.html]. As part of th=
e maven build process, style checking is performed using the Checkstyle plu=
gin, using the properties specified in checkstyle.xml. Committed code shoul=
d generate no Checkstyle errors. One thing that Checkstyle will complain ab=
out is tabs included in the source code. Please make sure to set your IDE o=
r editor to use spaces instead of tabs.
> Committers should make sure that svn properties are correctly set on file=
s added to the repository. See the section on Committer Subversion Access o=
n the Apache Source Code Repositories page.
> h3. Documentation
> * Committed code must include full javadoc.
> * All component contracts must be fully specified in the javadoc class, i=
nterface or method comments, including specification of acceptable ranges o=
f values, exceptions or special return values.
> * External references or full statements of definitions for all mathemati=
cal terms used in component documentation must be provided.
> * Implementations should use standard algorithms and references or full d=
escriptions of all algorithms should be provided.
> * Additions and enhancements should include updates to the User Guide.

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrato=
rs
For more information on JIRA, see: http://www.atlassian.com/software/jira