[
https://issues.apache.org/jira/browse/MATH-852?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13457767#comment-13457767
]
Gilles commented on MATH-852:
-----------------------------
bq. I like the approach in the javadoc tutorial [...]
Please note that the Java API docs do not seem to follow this tutorial (at
least not consistently): many single-line "@param" descriptions end with a
period!
bq. [...] one line fragments are not ended with a period whereas if there is an
additional description, they are separated by a period [...]
I simply don't like something that looks like the result of laziness. Why do 2
different things when the difference is just adding a "."?
For the indentation, it's a practical argument. As I said, your example looks
nice until one will have to e.g. change the name of one of the parameters: the
alignment will be broken and to recover it, you might have to touch things that
wouldn't have been without this alignment requirement (consequently: more lines
changed in the commit)...
This is nicely aligned:
{noformat}
* @param text1 the text of the tool tip
* @param text1 the string to display. If the text is null,
* the tool tip is turned off for this component.
{noformat}
Oh, you made a copy/paste mistake: the parameter names. I'm going to fix the
doc:
{noformat}
* @param textForSpeed the text of the tool tip
* @param textForAcceleration the string to display. If the text is null,
* the tool tip is turned off for this component.
{noformat}
Oops.
And (since we aim for fully illustrative parameter names), we are going to have
a lot of quite large gaps
and lines pushed far to the right:
{noformat}
* @param textForSpeed the text of the tool tip
* @param textForAcceleration the string to display. If the text is null,
* the tool tip is turned off for this component.
{noformat}
Please note: I agree that it is looking nicer, but "nice" is the goal of the
_formatted_ docs. Within the code, we should aim for "simple", and just as
readable as any piece of text which we are used to read.
Comments are supposed to be a plain English description of some code; I don't
see the point in trying to invent a new English syntax and punctuation system.
;)
> 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
