[
https://issues.apache.org/jira/browse/MATH-852?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13457630#comment-13457630
]
Thomas Neidhart commented on MATH-852:
--------------------------------------
Regarding the javadoc formatting, I like the formatting proposed in the
[Javadoc
Tutorial|http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html],
see an example:
{noformat}
/**
* Returns an Image object that can then be painted on the screen.
* The url argument must specify an absolute {@link URL}. The name
* argument is a specifier that is relative to the url argument.
* <p>
* This method always returns immediately, whether or not the
* image exists. When this applet attempts to draw the image on
* the screen, the data will be loaded. The graphics primitives
* that draw the image will incrementally paint on the screen.
*
* @param url an absolute URL giving the base location of the image
* @param name the location of the image, relative to the url argument
* @return the image at the specified URL
* @see Image
*/
public Image getImage(URL url, String name) {
try {
return getImage(new URL(url, name));
} catch (MalformedURLException e) {
return null;
}
}
{noformat}
Some comments on the rules:
* I prefer non-closing <p> tags on a separate line, this is much more readable
and takes less space
* @param and @return comments should not require a closing period
Regarding the example:
{noformat}
/**
* @param x First argument.
* @param y The second argument, always positive. This is a rather long comment,
* which should not be indented when reaching the second line.
* @return value.
*/
{noformat}
I am not sure about the indentation of the long comment, but I normally use two
spaces in the next line to make a better distinction with the next tag, like
this (but could also use more spaces):
{noformat}
/**
* @param x First argument.
* @param y The second argument, always positive. This is a rather long comment,
* which should not be indented when reaching the second line.
* @return value.
*/
{noformat}
> 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ébastien Brisard
> Labels: formatting, guidelines
>
> Recent discussions (see MATH-851, as well as these threads
> [1|http://markmail.org/thread/utxuipyolpnche5o],
> [2|http://markmail.org/thread/sma3nwa5j3hspvp5]) have shown that our actual
> requirements (especially regarding formatting) are higher than stated in the
> Developer's Guide. This leads to confusion among new contributors, as well as
> recent committers. It is therefore proposed to revise this guide, in order
> for it to reflect the actual expectations 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. superfluous
> 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 the maven build process, style checking is performed using the
> Checkstyle plugin, using the properties specified in checkstyle.xml.
> Committed code should generate no Checkstyle errors. One thing that
> Checkstyle will complain about is tabs included in the source code. Please
> make sure to set your IDE or editor to use spaces instead of tabs.
> Committers should make sure that svn properties are correctly set on files
> added to the repository. See the section on Committer Subversion Access on
> 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,
> interface or method comments, including specification of acceptable ranges of
> values, exceptions or special return values.
> * External references or full statements of definitions for all mathematical
> terms used in component documentation must be provided.
> * Implementations should use standard algorithms and references or full
> descriptions 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 administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira
