commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gilles Sadowski <gil...@harfang.homelinux.org>
Subject Re: svn commit: r1056412 - in /commons/proper/math/trunk/src/main/java/org/apache/commons/math/optimization: BaseMultiStartMultivariateRealOptimizer.java BaseMultiStartMultivariateVectorialOptimizer.java
Date Fri, 07 Jan 2011 18:20:07 GMT
Hi.

> Author: sebb
> Date: Fri Jan  7 17:47:14 2011
> New Revision: 1056412
> 
> URL: http://svn.apache.org/viewvc?rev=1056412&view=rev
> Log:
> MATH-466 - update Javadoc
> 
> Modified:
>     commons/proper/math/trunk/src/main/java/org/apache/commons/math/optimization/BaseMultiStartMultivariateRealOptimizer.java
>     commons/proper/math/trunk/src/main/java/org/apache/commons/math/optimization/BaseMultiStartMultivariateVectorialOptimizer.java
> 
> Modified: commons/proper/math/trunk/src/main/java/org/apache/commons/math/optimization/BaseMultiStartMultivariateRealOptimizer.java
> URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math/optimization/BaseMultiStartMultivariateRealOptimizer.java?rev=1056412&r1=1056411&r2=1056412&view=diff
> ==============================================================================
> --- commons/proper/math/trunk/src/main/java/org/apache/commons/math/optimization/BaseMultiStartMultivariateRealOptimizer.java
(original)
> +++ commons/proper/math/trunk/src/main/java/org/apache/commons/math/optimization/BaseMultiStartMultivariateRealOptimizer.java
Fri Jan  7 17:47:14 2011
> @@ -60,7 +60,8 @@ public class BaseMultiStartMultivariateR
>       * Create a multi-start optimizer from a single-start optimizer.
>       *
>       * @param optimizer Single-start optimizer to wrap.
> -     * @param starts Number of starts to perform.
> +     * @param starts Number of starts to perform, must be >=1. 
                                                    ^^^^^^^^^^^^^
This is redundant with the information provided in the @throws tag:
---
  * @throws NotStrictlyPositiveException if {@code starts < 1}.
---
Sometimes, when the reason for some checks might not be obvious, There could
be a more detailed explanation (in the Javdoc "description" paragraph), but
otherwise, I'm against redundant statements.

>From a formatting point-of-view, when correting Javadocs, I think that we
should write full English sentences:
---
  * @param starts Number of starts to perform. It must be strictly positive.
---
[If mathematical pseudo-code is needed, I'd write it within a {@code ...}
construct, as you did below.]

> +     * Multi-start is disabled if {@code starts == 1}.

And this is slightly misleading since there is no special disabling code.
It should be obvious to the use that multi-start with a value of "1" is not
really "multi"!


Best regards,
Gilles

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message