Re: [1/4] commons-rng git commit: Fixed the javadoc errors with Java 8

Wed, 28 Sep 2016 06:07:05 -0700 

Emmanuel,

On Wed, 28 Sep 2016 08:54:50 -0000, ebo...@apache.org wrote:

Repository: commons-rng
Updated Branches:
  refs/heads/master fcc9da888 -> fd22dc61f


Fixed the javadoc errors with Java 8


I use Java 8 and did not get any errors when generating the apidocs.

Unless I'm missing something, the above message does not correspond
to the change in this commit.

The changes themselves contradict usage of the <p> HTML tag: <p> and
</p> enclose a paragraph, not a headline.

So I think that this change should be reverted.

Then please let us know what problems you encountered so we can
decide _together_ on how we want Javadoc to be written for this
component (and possibly others).


Thanks,
Gilles


Project: http://git-wip-us.apache.org/repos/asf/commons-rng/repo
Commit: http://git-wip-us.apache.org/repos/asf/commons-rng/commit/41830f7d Tree: http://git-wip-us.apache.org/repos/asf/commons-rng/tree/41830f7d Diff: http://git-wip-us.apache.org/repos/asf/commons-rng/diff/41830f7d 

Branch: refs/heads/master
Commit: 41830f7d94bfdb53c04b5c76986f3272fe6cfe64
Parents: fcc9da8
Author: Emmanuel Bourg <ebo...@apache.org>
Authored: Wed Sep 28 10:05:47 2016 +0200
Committer: Emmanuel Bourg <ebo...@apache.org>
Committed: Wed Sep 28 10:05:47 2016 +0200


----------------------------------------------------------------------
.../org/apache/commons/rng/RandomSource.java | 28 ++++++++------------ 
 .../rng/internal/source32/MersenneTwister.java  |  2 +-
 .../internal/source64/MersenneTwister64.java    |  2 +-
 .../commons/rng/internal/source64/TwoCmres.java |  5 ++--
 .../rng/internal/util/NumberFactory.java        | 17 ++++++------
 5 files changed, 24 insertions(+), 30 deletions(-)

----------------------------------------------------------------------



http://git-wip-us.apache.org/repos/asf/commons-rng/blob/41830f7d/src/main/java/org/apache/commons/rng/RandomSource.java

----------------------------------------------------------------------
diff --git a/src/main/java/org/apache/commons/rng/RandomSource.java
b/src/main/java/org/apache/commons/rng/RandomSource.java
index 0c22419..27b67bb 100644
--- a/src/main/java/org/apache/commons/rng/RandomSource.java
+++ b/src/main/java/org/apache/commons/rng/RandomSource.java
@@ -23,8 +23,8 @@ import org.apache.commons.rng.internal.util.SeedFactory; 

 /**
* This class provides the API for creating generators of random numbers. 
- * <p>
- * Usage examples:
+ *
+ * <p>Usage examples:</p>
  * <pre><code>
* UniformRandomProvider rng = RandomSource.create(RandomSource.MT); 
  * </code></pre>
@@ -41,7 +41,8 @@ import org.apache.commons.rng.internal.util.SeedFactory; * where the first argument to method {@code create} is the identifier * of the generator's concrete implementation, and the second the is the 
  * (optional) seed.
- * <br>
+ *
+ * <p>
* In the first form, a random seed will be {@link SeedFactory generated * automatically}; in the second form, a fixed seed is used; a random seed 
  * is explicitly generated in the third form.
@@ -105,9 +106,11 @@ import org.apache.commons.rng.internal.util.SeedFactory; * or arrays of values, of {@code int} or {@code long} types) that can * be passed to the {@link RandomSource#create(RandomSource,Object,Object[]) 
  * generators factory method}.
- * <br>
+ * </p>
+ * <p>
* Although the seed-generating methods defined in this class will likely * return different values each time they are called, there is no guarantee: 
+ * </p>
  * <ul>
  *  <li>
  *   In any sub-sequence, it is <a
href="https://en.wikipedia.org/wiki/Birthday_problem";>
@@ -126,7 +129,6 @@ import org.apache.commons.rng.internal.util.SeedFactory; 
  *   or <a
href="http://simul.iro.umontreal.ca/testu01/tu01.html";>TestU01</a>.
  *  </li>
  * </ul>
- * </p>
  *
  * <p>
  * The current implementations have no provision for producing
non-overlapping
@@ -365,12 +367,10 @@ public enum RandomSource {
     /**
      * Creates a random number generator with a random seed.
      *
-     * <p>
-     * Example of usage:
+     * <p>Example of usage:</p>
      * <pre><code>
* UniformRandomProvider rng = RandomSource.create(RandomSource.MT); 
      * </code></pre>
-     * </p>
      *
      * @param source RNG type.
      * @return the RNG.
@@ -382,15 +382,12 @@ public enum RandomSource {
     /**
* Creates a random number generator with the given {@code seed}. 
      *
-     * <p>
-     * Example of usage:
+     * <p>Example of usage:</p>
      * <pre><code>
      *  UniformRandomProvider rng =
RandomSource.create(RandomSource.TWO_CMRES_SELECT, 26219, 6, 9);
      * </code></pre>
-     * </p>
      *
-     * <p>
-     * Valid types for the {@code seed} are:
+     * <p>Valid types for the {@code seed} are:</p>
      *  <ul>
      *   <li>{@code Integer} (or {@code int})</li>
      *   <li>{@code Long} (or {@code long})</li>
@@ -398,10 +395,8 @@ public enum RandomSource {
      *   <li>{@code long[]}</li>
      *   <li>{@code byte[]}</li>
      *  </ul>
-     * </p>
      *
-     * <p>
-     * Notes:
+     * <p>Notes:</p>
      * <ul>
      *  <li>
* When the seed type passed as argument is more complex (i.e. more 
@@ -419,7 +414,6 @@ public enum RandomSource {
      *   {@code null}, the size of the generated array will be 128.
      *  </li>
      * </ul>
-     * </p>
      *
      * @param source RNG type.
* @param seed Seed value. It can be {@code null} (in which case a 


http://git-wip-us.apache.org/repos/asf/commons-rng/blob/41830f7d/src/main/java/org/apache/commons/rng/internal/source32/MersenneTwister.java

----------------------------------------------------------------------
diff --git

a/src/main/java/org/apache/commons/rng/internal/source32/MersenneTwister.java

b/src/main/java/org/apache/commons/rng/internal/source32/MersenneTwister.java
index e53ac4e..0626a7d 100644
---

a/src/main/java/org/apache/commons/rng/internal/source32/MersenneTwister.java
+++

b/src/main/java/org/apache/commons/rng/internal/source32/MersenneTwister.java
@@ -49,7 +49,7 @@ import org.apache.commons.rng.internal.util.NumberFactory; 
  * and Takuji Nishimura. Here is their original copyright:
  * </p>
  *
- * <table border="0" width="80%" cellpadding="10" align="center"
bgcolor="#E0E0E0">
+ * <table border="0" width="80%" cellpadding="10"
style="background-color: #E0E0E0" summary="Mersenne Twister licence">
* <tr><td>Copyright (C) 1997 - 2002, Makoto Matsumoto and Takuji Nishimura, 
  *     All rights reserved.</td></tr>
  *


http://git-wip-us.apache.org/repos/asf/commons-rng/blob/41830f7d/src/main/java/org/apache/commons/rng/internal/source64/MersenneTwister64.java

----------------------------------------------------------------------
diff --git

a/src/main/java/org/apache/commons/rng/internal/source64/MersenneTwister64.java

b/src/main/java/org/apache/commons/rng/internal/source64/MersenneTwister64.java
index bee7ece..8943ba6 100644
---

a/src/main/java/org/apache/commons/rng/internal/source64/MersenneTwister64.java
+++

b/src/main/java/org/apache/commons/rng/internal/source64/MersenneTwister64.java
@@ -35,7 +35,7 @@ import org.apache.commons.rng.internal.util.NumberFactory; 
  * Here is their original copyright:
  * </p>
  *
- * <table border="0" width="80%" cellpadding="10" align="center"
bgcolor="#E0E0E0">
+ * <table border="0" width="80%" cellpadding="10"
style="background-color: #E0E0E0" summary="Mersenne Twister licence">
* <tr><td>Copyright (C) 2004, Makoto Matsumoto and Takuji Nishimura, 
  *     All rights reserved.</td></tr>
  *


http://git-wip-us.apache.org/repos/asf/commons-rng/blob/41830f7d/src/main/java/org/apache/commons/rng/internal/source64/TwoCmres.java

----------------------------------------------------------------------
diff --git

a/src/main/java/org/apache/commons/rng/internal/source64/TwoCmres.java

b/src/main/java/org/apache/commons/rng/internal/source64/TwoCmres.java
index 8afe220..2427f60 100644
--- a/src/main/java/org/apache/commons/rng/internal/source64/TwoCmres.java +++ b/src/main/java/org/apache/commons/rng/internal/source64/TwoCmres.java 
@@ -23,13 +23,12 @@ import
org.apache.commons.rng.internal.util.NumberFactory;

 /**
  * Random number generator designed by Mark D.&nbsp;Overton.
- * <p>
- *  It is one of the many generators described by the author in the
following article series:
+ *
+ * <p>It is one of the many generators described by the author in
the following article series:</p>
  *  <ul>
  *   <li><a

href="http://www.drdobbs.com/tools/fast-high-quality-parallel-random-number/229625477";>Part
one</a></li>
  *   <li><a

href="http://www.drdobbs.com/tools/fast-high-quality-parallel-random-number/231000484";>Part
two</a></li>
  *  </ul>
- * </p>
  *
  * @since 1.0
  */


http://git-wip-us.apache.org/repos/asf/commons-rng/blob/41830f7d/src/main/java/org/apache/commons/rng/internal/util/NumberFactory.java

----------------------------------------------------------------------
diff --git

a/src/main/java/org/apache/commons/rng/internal/util/NumberFactory.java

b/src/main/java/org/apache/commons/rng/internal/util/NumberFactory.java
index b769db6..22f1d16 100644
--- a/src/main/java/org/apache/commons/rng/internal/util/NumberFactory.java +++ b/src/main/java/org/apache/commons/rng/internal/util/NumberFactory.java 
@@ -112,14 +112,14 @@ public final class NumberFactory {

     /**
      * Creates an {@code int} from a {@code long}, using the high
order bits.
-     * <p>
-     * The returned value is such that if
+     *
+     * <p>The returned value is such that if</p>
      * <pre><code>
      *  vL = extractLo(v);
      *  vH = extractHi(v);
      * </code></pre>
-     * then {@code v} is equal to {@link #makeLong(int,int)
makeLong(vH, vL)}.
-     * </p>
+     *
+     * <p>then {@code v} is equal to {@link #makeLong(int,int)
makeLong(vH, vL)}.</p>
      *
      * @param v Number.
* @return an {@code int} value made from the most significant bits 
@@ -131,14 +131,15 @@ public final class NumberFactory {

     /**
* Creates an {@code int} from a {@code long}, using the low order bits. 
-     * <p>
-     * The returned value is such that if
+     *
+     * <p>The returned value is such that if</p>
+     *
      * <pre><code>
      *  vL = extractLo(v);
      *  vH = extractHi(v);
      * </code></pre>
-     * then {@code v} is equal to {@link #makeLong(int,int)
makeLong(vH, vL)}.
-     * </p>
+     *
+     * <p>then {@code v} is equal to {@link #makeLong(int,int)
makeLong(vH, vL)}.</p>
      *
      * @param v Number.
* @return an {@code int} value made from the least significant bits 


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

Reply via email to