Merge pull request #39 from str4d/37-javadoc-errors

Fix errors and warnings in JavaDocs

Part of #37.

Author: str4d

pom.xml

@@ -98,6 +98,9 @@
         <artifactId>maven-javadoc-plugin</artifactId>
         <version>2.9.1</version>
         <configuration>
+          <charset>UTF-8</charset>
+          <docencoding>UTF-8</docencoding>
+          <encoding>UTF-8</encoding>
           <header>&lt;script type='text/x-mathjax-config'&gt;
   MathJax.Hub.Config({
     tex2jax: {
@@ -107,6 +110,8 @@
   });
 &lt;/script&gt;
 &lt;script type='text/javascript' src='https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML'&gt;&lt;/script&gt;</header>
+          <!-- Required for Java 8u121 or later. See https://github.com/neo4j/neo4j-java-driver/pull/318  -->
+          <!--<additionalparam>&#45;&#45;allow-script-in-comments</additionalparam>-->
         </configuration>
         <executions>
           <execution>

src/net/i2p/crypto/eddsa/EdDSAEngine.java

@@ -318,6 +318,8 @@ private boolean x_engineVerify(byte[] sigBytes) throws SignatureException {
      *  sig = sign()
      *</pre>
      *
+     * @param data the message to be signed
+     * @return the signature
      * @throws SignatureException if update() already called
      * @see #ONE_SHOT_MODE
      */
@@ -336,6 +338,10 @@ public byte[] signOneShot(byte[] data) throws SignatureException {
      *  sig = sign()
      *</pre>
      *
+     * @param data byte array containing the message to be signed
+     * @param off the start of the message inside data
+     * @param len the length of the message
+     * @return the signature
      * @throws SignatureException if update() already called
      * @see #ONE_SHOT_MODE
      */
@@ -356,6 +362,9 @@ public byte[] signOneShot(byte[] data, int off, int len) throws SignatureExcepti
      *  ok = verify(signature)
      *</pre>
      *
+     * @param data the message that was signed
+     * @param signature of the message
+     * @return true if the signature is valid, false otherwise
      * @throws SignatureException if update() already called
      * @see #ONE_SHOT_MODE
      */
@@ -374,6 +383,11 @@ public boolean verifyOneShot(byte[] data, byte[] signature) throws SignatureExce
      *  ok = verify(signature)
      *</pre>
      *
+     * @param data byte array containing the message that was signed
+     * @param off the start of the message inside data
+     * @param len the length of the message
+     * @param signature of the message
+     * @return true if the signature is valid, false otherwise
      * @throws SignatureException if update() already called
      * @see #ONE_SHOT_MODE
      */
@@ -392,6 +406,11 @@ public boolean verifyOneShot(byte[] data, int off, int len, byte[] signature) th
      *  ok = verify(signature, sigoff, siglen)
      *</pre>
      *
+     * @param data the message that was signed
+     * @param signature byte array containing the signature
+     * @param sigoff the start of the signature
+     * @param siglen the length of the signature
+     * @return true if the signature is valid, false otherwise
      * @throws SignatureException if update() already called
      * @see #ONE_SHOT_MODE
      */
@@ -410,6 +429,13 @@ public boolean verifyOneShot(byte[] data, byte[] signature, int sigoff, int sigl
      *  ok = verify(signature, sigoff, siglen)
      *</pre>
      *
+     * @param data byte array containing the message that was signed
+     * @param off the start of the message inside data
+     * @param len the length of the message
+     * @param signature byte array containing the signature
+     * @param sigoff the start of the signature
+     * @param siglen the length of the signature
+     * @return true if the signature is valid, false otherwise
      * @throws SignatureException if update() already called
      * @see #ONE_SHOT_MODE
      */
@@ -435,7 +461,7 @@ protected void engineSetParameter(AlgorithmParameterSpec spec) throws InvalidAlg
     }
 
     /**
-     * @deprecated replaced with <a href="#engineSetParameter(java.security.spec.AlgorithmParameterSpec)">
+     * @deprecated
      */
     @Override
     protected void engineSetParameter(String param, Object value) {

src/net/i2p/crypto/eddsa/EdDSAKey.java

@@ -24,8 +24,8 @@ public interface EdDSAKey {
     String KEY_ALGORITHM = "EdDSA";
 
     /**
-     * return a parameter specification representing the EdDSA domain
-     * parameters for the key.
+     * @return a parameter specification representing the EdDSA domain
+     *         parameters for the key.
      */
     EdDSAParameterSpec getParams();
 }

src/net/i2p/crypto/eddsa/Utils.java

@@ -21,6 +21,8 @@
 public class Utils {
     /**
      * Constant-time byte comparison.
+     * @param b a byte
+     * @param c a byte
      * @return 1 if b and c are equal, 0 otherwise.
      */
     public static int equal(int b, int c) {
@@ -34,6 +36,8 @@ public static int equal(int b, int c) {
 
     /**
      * Constant-time byte[] comparison.
+     * @param b a byte[]
+     * @param c a byte[]
      * @return 1 if b and c are equal, 0 otherwise.
      */
     public static int equal(byte[] b, byte[] c) {

src/net/i2p/crypto/eddsa/math/Encoding.java

@@ -28,6 +28,7 @@ public synchronized void setField(Field f) {
 
     /**
      * Encode a FieldElement in its $(b-1)$-bit encoding.
+     * @param x the FieldElement to encode
      * @return the $(b-1)$-bit encoding of this FieldElement.
      */
     public abstract byte[] encode(FieldElement x);
@@ -46,6 +47,7 @@ public synchronized void setField(Field f) {
      * than the $(b-1)$-bit encoding of -x. If $q$ is an odd prime and the encoding
      * is the little-endian representation of $\{0, 1,\dots, q-1\}$ then the negative
      * elements of $F_q$ are $\{1, 3, 5,\dots, q-2\}$.
+     * @param x the FieldElement to check
      * @return true if negative
      */
     public abstract boolean isNegative(FieldElement x);

src/net/i2p/crypto/eddsa/math/GroupElement.java

@@ -36,12 +36,13 @@ public class GroupElement implements Serializable {
 
     /**
      * Available representations for a group element.
-     * <p><ul>
+     * <ul>
      * <li>P2: Projective representation $(X:Y:Z)$ satisfying $x=X/Z, y=Y/Z$.
      * <li>P3: Extended projective representation $(X:Y:Z:T)$ satisfying $x=X/Z, y=Y/Z, XY=ZT$.
      * <li>P1P1: Completed representation $((X:Z), (Y:T))$ satisfying $x=X/Z, y=Y/T$.
      * <li>PRECOMP: Precomputed representation $(y+x, y-x, 2dxy)$.
      * <li>CACHED: Cached representation $(Y+X, Y-X, Z, 2dT)$
+     * </ul>
      */
     public enum Representation {
         /** Projective ($P^2$): $(X:Y:Z)$ satisfying $x=X/Z, y=Y/Z$ */
@@ -223,12 +224,13 @@ public GroupElement(
      * <p>
      * A point $(x,y)$ is encoded by storing $y$ in bit 0 to bit 254 and the sign of $x$ in bit 255.
      * $x$ is recovered in the following way:
-     * <p><ul>
+     * </p><ul>
      * <li>$x = sign(x) * \sqrt{(y^2 - 1) / (d * y^2 + 1)} = sign(x) * \sqrt{u / v}$ with $u = y^2 - 1$ and $v = d * y^2 + 1$.
      * <li>Setting $β = (u * v^3) * (u * v^7)^{((q - 5) / 8)}$ one has $β^2 = \pm(u / v)$.
      * <li>If $v * β = -u$ multiply $β$ with $i=\sqrt{-1}$.
      * <li>Set $x := β$.
      * <li>If $sign(x) \ne$ bit 255 of $s$ then negate $x$.
+     * </ul>
      *
      * @param curve The curve.
      * @param s The encoded point.
@@ -503,7 +505,7 @@ public synchronized void precompute(final boolean precomputeSingle) {
      * $r$ in $P \times P$ representation:
      * <p>
      * $r = ((X' : Z'), (Y' : T'))$ where
-     * <p><ul>
+     * </p><ul>
      * <li>$X' = (X + Y)^2 - (Y^2 + X^2)$
      * <li>$Y' = Y^2 + X^2$
      * <li>$Z' = y^2 - X^2$
@@ -512,7 +514,7 @@ public synchronized void precompute(final boolean precomputeSingle) {
      * $r$ converted from $P \times P$ to $P^2$ representation:
      * <p>
      * $r = (X'' : Y'' : Z'')$ where
-     * <p><ul>
+     * </p><ul>
      * <li>$X'' = X' * Z' = ((X + Y)^2 - Y^2 - X^2) * (2 * Z^2 - (y^2 - X^2))$
      * <li>$Y'' = Y' * T' = (Y^2 + X^2) * (2 * Z^2 - (y^2 - X^2))$
      * <li>$Z'' = Z' * T' = (y^2 - X^2) * (2 * Z^2 - (y^2 - X^2))$
@@ -645,14 +647,14 @@ private GroupElement msub(GroupElement q) {
      * $r = p + q$ where $p = this = (X1 : Y1 : Z1 : T1), q = (q.X, q.Y, q.Z, q.T) = (Y2 + X2, Y2 - X2, Z2, 2 * d * T2)$
      * <p>
      * $r$ in $P \times P$ representation:
-     * <p><ul>
+     * </p><ul>
      * <li>$X' = (Y1 + X1) * (Y2 + X2) - (Y1 - X1) * (Y2 - X2)$
      * <li>$Y' = (Y1 + X1) * (Y2 + X2) + (Y1 - X1) * (Y2 - X2)$
      * <li>$Z' = 2 * Z1 * Z2 + 2 * d * T1 * T2$
      * <li>$T' = 2 * Z1 * T2 - 2 * d * T1 * T2$
      * </ul><p>
      * Setting $A = (Y1 - X1) * (Y2 - X2), B = (Y1 + X1) * (Y2 + X2), C = 2 * d * T1 * T2, D = 2 * Z1 * Z2$ we get
-     * <p><ul>
+     * </p><ul>
      * <li>$X' = (B - A)$
      * <li>$Y' = (B + A)$
      * <li>$Z' = (D + C)$
@@ -864,7 +866,7 @@ GroupElement select(final int pos, final int b) {
      * Constant time.
      * <p>
      * Preconditions: (TODO: Check this applies here)
-     *   $a[31] <= 127$
+     *   $a[31] \le 127$
      * @param a $= a[0]+256*a[1]+\dots+256^{31} a[31]$
      * @return the GroupElement
      */

src/net/i2p/crypto/eddsa/math/ScalarOps.java

@@ -18,16 +18,16 @@ public interface ScalarOps {
      * From the Ed25519 paper:<br>
      * Here we interpret $2b$-bit strings in little-endian form as integers in
      * $\{0, 1,..., 2^{(2b)}-1\}$.
-     * @param s
+     * @param s the scalar to reduce
      * @return $s \bmod l$
      */
     public byte[] reduce(byte[] s);
 
     /**
      * $r = (a * b + c) \bmod l$
-     * @param a
-     * @param b
-     * @param c
+     * @param a a scalar
+     * @param b a scalar
+     * @param c a scalar
      * @return $(a*b + c) \bmod l$
      */
     public byte[] multiplyAndAdd(byte[] a, byte[] b, byte[] c);

src/net/i2p/crypto/eddsa/math/bigint/BigIntegerLittleEndianEncoding.java

@@ -39,6 +39,7 @@ public byte[] encode(FieldElement x) {
      *  Convert $x$ to little endian.
      *  Constant time.
      *
+     *  @param x the BigInteger value to encode
      *  @return array of length $b/8$
      *  @throws IllegalStateException if field not set
      */
@@ -75,6 +76,9 @@ public FieldElement decode(byte[] in) {
 
     /**
      *  Convert in to big endian
+     *
+     *  @param in the $(b-1)$-bit encoding of a FieldElement.
+     *  @return the decoded value as a BigInteger
      */
     public BigInteger toBigInteger(byte[] in) {
         byte[] out = new byte[in.length];

src/net/i2p/crypto/eddsa/math/ed25519/Ed25519FieldElement.java

@@ -62,13 +62,14 @@ public boolean isNonZero() {
      * TODO-CR BR: $h$ is allocated via new, probably not a good idea. Do we need the copying into temp variables if we do that?
      * <p>
      * Preconditions:
-     * <p><ul>
+     * </p><ul>
      * <li>$|f|$ bounded by $1.1*2^{25},1.1*2^{24},1.1*2^{25},1.1*2^{24},$ etc.
      * <li>$|g|$ bounded by $1.1*2^{25},1.1*2^{24},1.1*2^{25},1.1*2^{24},$ etc.
      * </ul><p>
      * Postconditions:
-     * <p><ul>
+     * </p><ul>
      * <li>$|h|$ bounded by $1.1*2^{26},1.1*2^{25},1.1*2^{26},1.1*2^{25},$ etc.
+     * </ul>
      *
      * @param val The field element to add.
      * @return The field element this + val.
@@ -90,13 +91,14 @@ public FieldElement add(FieldElement val) {
      * TODO-CR BR: See above.
      * <p>
      * Preconditions:
-     * <p><ul>
+     * </p><ul>
      * <li>$|f|$ bounded by $1.1*2^{25},1.1*2^{24},1.1*2^{25},1.1*2^{24},$ etc.
      * <li>$|g|$ bounded by $1.1*2^{25},1.1*2^{24},1.1*2^{25},1.1*2^{24},$ etc.
      * </ul><p>
      * Postconditions:
-     * <p><ul>
+     * </p><ul>
      * <li>$|h|$ bounded by $1.1*2^{26},1.1*2^{25},1.1*2^{26},1.1*2^{25},$ etc.
+     * </ul>
      *
      * @param val The field element to subtract.
      * @return The field element this - val.
@@ -116,12 +118,13 @@ public FieldElement subtract(FieldElement val) {
      * TODO-CR BR: see above.
      * <p>
      * Preconditions:
-     * <p><ul>
+     * </p><ul>
      * <li>$|f|$ bounded by $1.1*2^{25},1.1*2^{24},1.1*2^{25},1.1*2^{24},$ etc.
      * </ul><p>
      * Postconditions:
-     * <p><ul>
+     * </p><ul>
      * <li>$|h|$ bounded by $1.1*2^{25},1.1*2^{24},1.1*2^{25},1.1*2^{24},$ etc.
+     * </ul>
      *
      * @return The field element (-1) * this.
      */
@@ -139,14 +142,14 @@ public FieldElement negate() {
      * Can overlap $h$ with $f$ or $g$.
      * <p>
      * Preconditions:
-     * <p><ul>
+     * </p><ul>
      * <li>$|f|$ bounded by
      * $1.65*2^{26},1.65*2^{25},1.65*2^{26},1.65*2^{25},$ etc.
      * <li>$|g|$ bounded by
      * $1.65*2^{26},1.65*2^{25},1.65*2^{26},1.65*2^{25},$ etc.
      * </ul><p>
      * Postconditions:
-     * <p><ul>
+     * </p><ul>
      * <li>$|h|$ bounded by
      * $1.01*2^{25},1.01*2^{24},1.01*2^{25},1.01*2^{24},$ etc.
      * </ul><p>
@@ -390,11 +393,11 @@ public FieldElement multiply(FieldElement val) {
      * Can overlap $h$ with $f$.
      * <p>
      * Preconditions:
-     * <p><ul>
+     * </p><ul>
      * <li>$|f|$ bounded by $1.65*2^{26},1.65*2^{25},1.65*2^{26},1.65*2^{25},$ etc.
      * </ul><p>
      * Postconditions:
-     * <p><ul>
+     * </p><ul>
      * <li>$|h|$ bounded by $1.01*2^{25},1.01*2^{24},1.01*2^{25},1.01*2^{24},$ etc.
      * </ul><p>
      * See {@link #multiply(FieldElement)} for discussion
@@ -546,11 +549,11 @@ public FieldElement square() {
      * Can overlap $h$ with $f$.
      * <p>
      * Preconditions:
-     * <p><ul>
+     * </p><ul>
      * <li>$|f|$ bounded by $1.65*2^{26},1.65*2^{25},1.65*2^{26},1.65*2^{25},$ etc.
      * </ul><p>
      * Postconditions:
-     * <p><ul>
+     * </p><ul>
      * <li>$|h|$ bounded by $1.01*2^{25},1.01*2^{24},1.01*2^{25},1.01*2^{24},$ etc.
      * </ul><p>
      * See {@link #multiply(FieldElement)} for discussion

src/net/i2p/crypto/eddsa/math/ed25519/Ed25519LittleEndianEncoding.java

@@ -26,15 +26,15 @@ public class Ed25519LittleEndianEncoding extends Encoding {
      * <li>Convert the field element to the 32 byte representation.
      * </ol><p>
      * The idea for the modulo $p$ reduction algorithm is as follows:
-     * <p>
+     * </p>
      * <h2>Assumption:</h2>
-     * <p><ul>
+     * <ul>
      * <li>$p = 2^{255} - 19$
      * <li>$h = h_0 + 2^{25} * h_1 + 2^{(26+25)} * h_2 + \dots + 2^{230} * h_9$ where $0 \le |h_i| \lt 2^{27}$ for all $i=0,\dots,9$.
      * <li>$h \cong r \mod p$, i.e. $h = r + q * p$ for some suitable $0 \le r \lt p$ and an integer $q$.
      * </ul><p>
      * Then $q = [2^{-255} * (h + 19 * 2^{-25} * h_9 + 1/2)]$ where $[x] = floor(x)$.
-     * <p>
+     * </p>
      * <h2>Proof:</h2>
      * <p>
      * We begin with some very raw estimation for the bounds of some expressions:
@@ -242,8 +242,9 @@ public FieldElement decode(byte[] in) {
      * Return false if $x$ is in $\{0,2,4,\dots,q-1\}$
      * <p>
      * Preconditions:
-     * <p><ul>
+     * </p><ul>
      * <li>$|x|$ bounded by $1.1*2^{26},1.1*2^{25},1.1*2^{26},1.1*2^{25}$, etc.
+     * </ul>
      *
      * @return true if $x$ is in $\{1,3,5,\dots,q-2\}$, false otherwise.
      */