Fix javadoc errors in ocpp-common

Author: robert-s-ubi

ocpp-common/src/main/java/eu/chargetime/ocpp/Communicator.java

@@ -27,6 +27,7 @@ of this software and associated documentation files (the "Software"), to deal
 SOFTWARE.
 */
 
+import eu.chargetime.ocpp.feature.Feature;
 import eu.chargetime.ocpp.model.*;
 import java.util.ArrayDeque;
 import org.slf4j.Logger;
@@ -54,6 +55,7 @@ public abstract class Communicator {
    * @param payload the raw formatted payload.
    * @param type the expected return type.
    * @return the unpacked payload.
+   * @param <T> the type of the unpacked payload.
    * @throws Exception error occurred while converting.
    */
   public abstract <T> T unpackPayload(Object payload, Class<T> type) throws Exception;
@@ -70,7 +72,7 @@ public abstract class Communicator {
    * Create a call result envelope to transmit.
    *
    * @param uniqueId the id the receiver expects.
-   * @param action action name of the feature.
+   * @param action action name of the {@link Feature}.
    * @param payload packed payload.
    * @return a fully packed message ready to send.
    */
@@ -80,7 +82,7 @@ public abstract class Communicator {
    * Create a call envelope to transmit to the server.
    *
    * @param uniqueId the id the receiver must reply with.
-   * @param action action name of the feature.
+   * @param action action name of the {@link Feature}.
    * @param payload packed payload.
    * @return a fully packed message ready to send.
    */
@@ -90,6 +92,7 @@ public abstract class Communicator {
    * Create a call error envelope to transmit.
    *
    * @param uniqueId the id the receiver expects.
+   * @param action action name of the {@link Feature}.
    * @param errorCode an OCPP error code.
    * @param errorDescription an associated error description.
    * @return a fully packed message ready to send.
@@ -101,6 +104,7 @@ protected abstract Object makeCallError(
    * Create a call result error envelope to transmit.
    *
    * @param uniqueId the id the receiver expects.
+   * @param action action name of the {@link Feature}.
    * @param errorCode an OCPP error code.
    * @param errorDescription an associated error description.
    * @return a fully packed message ready to send.
@@ -112,7 +116,7 @@ protected abstract Object makeCallResultError(
    * Create a send envelope to transmit to the server.
    *
    * @param uniqueId the id of the message.
-   * @param action action name of the feature.
+   * @param action action name of the {@link Feature}.
    * @param payload packed payload.
    * @return a fully packed message ready to send.
    */
@@ -177,7 +181,7 @@ public void accept(CommunicatorEvents events) {
    * Request}s.
    *
    * @param uniqueId the id the receiver should use to reply.
-   * @param action action name of the {@link eu.chargetime.ocpp.feature.Feature}.
+   * @param action action name of the {@link Feature}.
    * @param request the outgoing {@link Request}
    */
   public synchronized void sendCall(String uniqueId, String action, Request request) {
@@ -222,6 +226,7 @@ public synchronized void sendCall(String uniqueId, String action, Request reques
    * Send a {@link Confirmation} reply to a {@link Request}.
    *
    * @param uniqueId the id the receiver expects.
+   * @param action action name of the {@link Feature}.
    * @param confirmation the outgoing {@link Confirmation}
    */
   public void sendCallResult(String uniqueId, String action, Confirmation confirmation) {
@@ -255,7 +260,8 @@ public void sendCallResult(String uniqueId, String action, Confirmation confirma
    * Send an error. If offline, the message is thrown away.
    *
    * @param uniqueId the id the receiver expects a response to.
-   * @param errorCode an OCPP error Code
+   * @param action action name of the {@link Feature}.
+   * @param errorCode an OCPP error Code.
    * @param errorDescription a associated error description.
    */
   public void sendCallError(
@@ -282,7 +288,8 @@ public void sendCallError(
    * Send a call result error. If offline, the message is thrown away.
    *
    * @param uniqueId the id the receiver expects a response to.
-   * @param errorCode an OCPP error Code
+   * @param action action name of the {@link Feature}.
+   * @param errorCode an OCPP error Code.
    * @param errorDescription a associated error description.
    */
   public void sendCallResultError(
@@ -310,7 +317,7 @@ public void sendCallResultError(
    * Send a {@link Request} which has no confirmation.
    *
    * @param uniqueId the id of the {@link Request}.
-   * @param action action name of the {@link eu.chargetime.ocpp.feature.Feature}.
+   * @param action action name of the {@link Feature}.
    * @param request the outgoing {@link Request}
    */
   public synchronized void send(String uniqueId, String action, Request request) {

ocpp-common/src/main/java/eu/chargetime/ocpp/Server.java

@@ -227,6 +227,7 @@ public void close() {
    * @throws UnsupportedFeatureException Thrown if the feature isn't among the list of supported
    *     features.
    * @throws OccurenceConstraintException Thrown if the request isn't valid.
+   * @throws NotConnectedException Thrown if session with passed sessionIndex is not found
    */
   public CompletableFuture<Confirmation> send(UUID sessionIndex, Request request)
       throws UnsupportedFeatureException, OccurenceConstraintException, NotConnectedException {
@@ -275,6 +276,9 @@ public CompletableFuture<Confirmation> send(UUID sessionIndex, Request request)
    * @param confirmation the {@link Confirmation} to the original {@link Request}.
    * @return a boolean indicating if pending request was found.
    * @throws NotConnectedException Thrown if session with passed sessionIndex is not found
+   * @throws UnsupportedFeatureException Thrown if the feature isn't among the list of supported
+   *     features.
+   * @throws OccurenceConstraintException Thrown if the request isn't valid.
    */
   public boolean asyncCompleteRequest(UUID sessionIndex, String uniqueId, Confirmation confirmation)
       throws NotConnectedException, UnsupportedFeatureException, OccurenceConstraintException {

ocpp-common/src/main/java/eu/chargetime/ocpp/Session.java

@@ -64,6 +64,8 @@ public class Session implements ISession {
    *
    * @param communicator send and receive messages.
    * @param queue store and restore requests based on unique ids.
+   * @param fulfiller the {@link PromiseFulfiller} to use
+   * @param featureRepository the {@link IFeatureRepository} to use
    */
   public Session(
       Communicator communicator,
@@ -150,6 +152,7 @@ public void removeRequest(String ticket) {
    * Send a {@link Confirmation} to a {@link Request}
    *
    * @param uniqueId the unique identification the receiver expects.
+   * @param action action name to identify the feature.
    * @param confirmation the {@link Confirmation} payload to send.
    */
   public void sendConfirmation(String uniqueId, String action, Confirmation confirmation) {

ocpp-common/src/main/java/eu/chargetime/ocpp/SessionEvents.java

@@ -47,6 +47,8 @@ public interface SessionEvents {
    *
    * @param request the {@link Request}.
    * @return a {@link Confirmation} to send as a response or {@code null} if none to send.
+   * @throws UnsupportedFeatureException Thrown if the feature isn't among the list of supported
+   *     features.
    */
   @Nullable
   Confirmation handleRequest(Request request) throws UnsupportedFeatureException;
@@ -57,6 +59,9 @@ public interface SessionEvents {
    * @param uniqueId the unique id used for the {@link Request}.
    * @param confirmation the {@link Confirmation} to the {@link Request}.
    * @return a boolean indicating if pending request was found.
+   * @throws UnsupportedFeatureException Thrown if the feature isn't among the list of supported
+   *     features.
+   * @throws OccurenceConstraintException Thrown if the request isn't valid.
    */
   boolean asyncCompleteRequest(String uniqueId, Confirmation confirmation)
       throws UnsupportedFeatureException, OccurenceConstraintException;

ocpp-common/src/main/java/eu/chargetime/ocpp/utilities/MoreObjects.java

@@ -697,6 +697,7 @@ static ToStringHelperImpl toStringHelper(Class<?> clazz) {
      * Object#getClass()}.
      *
      * @param className the name of the instance type
+     * @return an instance of {@link ToStringHelperImpl}
      */
     public static ToStringHelperImpl toStringHelper(String className) {
       return new ToStringHelperImpl(className);
@@ -722,6 +723,8 @@ private ToStringHelperImpl(String className) {
      * Configures the {@link ToStringHelperImpl} so {@link #toString()} will ignore properties with
      * null value. The order of calling this method, relative to the {@code add()}/{@code
      * addValue()} methods, is not significant.
+     *
+     * @return this instance of {@link ToStringHelperImpl}
      */
     public ToStringHelperImpl omitNullValues() {
       omitNullValues = true;
@@ -732,42 +735,88 @@ public ToStringHelperImpl omitNullValues() {
      * Adds a name/value pair to the formatted output in {@code name=value} format. If {@code value}
      * is {@code null}, the string {@code "null"} is used, unless {@link #omitNullValues()} is
      * called, in which case this name/value pair will not be added.
+     *
+     * @param name the name
+     * @param value the {@link Object} value
+     * @return this instance of {@link ToStringHelperImpl}
      */
     public ToStringHelperImpl add(String name, Object value) {
       return addHolder(name, value);
     }
 
-    /** Adds a name/value pair to the formatted output in {@code name=value} format. */
+    /**
+     * Adds a name/value pair to the formatted output in {@code name=value} format.
+     *
+     * @param name the name
+     * @param value the {@link ZonedDateTime} value
+     * @return this instance of {@link ToStringHelperImpl}
+     */
     public ToStringHelperImpl add(String name, ZonedDateTime value) {
       return addHolder(name, value);
     }
 
-    /** Adds a name/value pair to the formatted output in {@code name=value} format. */
+    /**
+     * Adds a name/value pair to the formatted output in {@code name=value} format.
+     *
+     * @param name the name
+     * @param value the {@code boolean} value
+     * @return this instance of {@link ToStringHelperImpl}
+     */
     public ToStringHelperImpl add(String name, boolean value) {
       return addHolder(name, String.valueOf(value));
     }
 
-    /** Adds a name/value pair to the formatted output in {@code name=value} format. */
+    /**
+     * Adds a name/value pair to the formatted output in {@code name=value} format.
+     *
+     * @param name the name
+     * @param value the {@code char} value
+     * @return this instance of {@link ToStringHelperImpl}
+     */
     public ToStringHelperImpl add(String name, char value) {
       return addHolder(name, String.valueOf(value));
     }
 
-    /** Adds a name/value pair to the formatted output in {@code name=value} format. */
+    /**
+     * Adds a name/value pair to the formatted output in {@code name=value} format.
+     *
+     * @param name the name
+     * @param value the {@code double} value
+     * @return this instance of {@link ToStringHelperImpl}
+     */
     public ToStringHelperImpl add(String name, double value) {
       return addHolder(name, String.valueOf(value));
     }
 
-    /** Adds a name/value pair to the formatted output in {@code name=value} format. */
+    /**
+     * Adds a name/value pair to the formatted output in {@code name=value} format.
+     *
+     * @param name the name
+     * @param value the {@code float} value
+     * @return this instance of {@link ToStringHelperImpl}
+     */
     public ToStringHelperImpl add(String name, float value) {
       return addHolder(name, String.valueOf(value));
     }
 
-    /** Adds a name/value pair to the formatted output in {@code name=value} format. */
+    /**
+     * Adds a name/value pair to the formatted output in {@code name=value} format.
+     *
+     * @param name the name
+     * @param value the {@code int} value
+     * @return this instance of {@link ToStringHelperImpl}
+     */
     public ToStringHelperImpl add(String name, int value) {
       return addHolder(name, String.valueOf(value));
     }
 
-    /** Adds a name/value pair to the formatted output in {@code name=value} format. */
+    /**
+     * Adds a name/value pair to the formatted output in {@code name=value} format.
+     *
+     * @param name the name
+     * @param value the {@code long} value
+     * @return this instance of {@link ToStringHelperImpl}
+     */
     public ToStringHelperImpl add(String name, long value) {
       return addHolder(name, String.valueOf(value));
     }
@@ -777,6 +826,9 @@ public ToStringHelperImpl add(String name, long value) {
      *
      * <p>It is strongly encouraged to use {@link #add(String, Object)} instead and give value a
      * readable name.
+     *
+     * @param value the {@link Object} value
+     * @return this instance of {@link ToStringHelperImpl}
      */
     public ToStringHelperImpl addValue(Object value) {
       return addHolder(value);
@@ -787,6 +839,9 @@ public ToStringHelperImpl addValue(Object value) {
      *
      * <p>It is strongly encouraged to use {@link #add(String, boolean)} instead and give value a
      * readable name.
+     *
+     * @param value the {@code boolean} value
+     * @return this instance of {@link ToStringHelperImpl}
      */
     public ToStringHelperImpl addValue(boolean value) {
       return addHolder(String.valueOf(value));
@@ -797,6 +852,9 @@ public ToStringHelperImpl addValue(boolean value) {
      *
      * <p>It is strongly encouraged to use {@link #add(String, char)} instead and give value a
      * readable name.
+     *
+     * @param value the {@code char} value
+     * @return this instance of {@link ToStringHelperImpl}
      */
     public ToStringHelperImpl addValue(char value) {
       return addHolder(String.valueOf(value));
@@ -807,6 +865,9 @@ public ToStringHelperImpl addValue(char value) {
      *
      * <p>It is strongly encouraged to use {@link #add(String, double)} instead and give value a
      * readable name.
+     *
+     * @param value the {@code double} value
+     * @return this instance of {@link ToStringHelperImpl}
      */
     public ToStringHelperImpl addValue(double value) {
       return addHolder(String.valueOf(value));
@@ -817,6 +878,9 @@ public ToStringHelperImpl addValue(double value) {
      *
      * <p>It is strongly encouraged to use {@link #add(String, float)} instead and give value a
      * readable name.
+     *
+     * @param value the {@code float} value
+     * @return this instance of {@link ToStringHelperImpl}
      */
     public ToStringHelperImpl addValue(float value) {
       return addHolder(String.valueOf(value));
@@ -827,6 +891,9 @@ public ToStringHelperImpl addValue(float value) {
      *
      * <p>It is strongly encouraged to use {@link #add(String, int)} instead and give value a
      * readable name.
+     *
+     * @param value the {@code int} value
+     * @return this instance of {@link ToStringHelperImpl}
      */
     public ToStringHelperImpl addValue(int value) {
       return addHolder(String.valueOf(value));
@@ -837,6 +904,9 @@ public ToStringHelperImpl addValue(int value) {
      *
      * <p>It is strongly encouraged to use {@link #add(String, long)} instead and give value a
      * readable name.
+     *
+     * @param value the {@code long} value
+     * @return this instance of {@link ToStringHelperImpl}
      */
     public ToStringHelperImpl addValue(long value) {
       return addHolder(String.valueOf(value));

ocpp-common/src/main/java/eu/chargetime/ocpp/utilities/Stopwatch.java

@@ -52,19 +52,28 @@ public interface Ticker {
 
   /**
    * Creates (but does not start) a new stopwatch using {@link System#nanoTime} as its time source.
+   *
+   * @return the new stopwatch (not started)
    */
   public static Stopwatch createUnstarted() {
     return new Stopwatch();
   }
 
-  /** Creates (and starts) a new stopwatch using {@link System#nanoTime} as its time source. */
+  /**
+   * Creates (and starts) a new stopwatch using {@link System#nanoTime} as its time source.
+   *
+   * @return the new stopwatch (started)
+   */
   public static Stopwatch createStarted() {
     return new Stopwatch().start();
   }
 
   /**
    * Returns {@code true} if {@link #start()} has been called on this stopwatch, and {@link #stop()}
    * has not been called since the last call to {@code start()}.
+   *
+   * @return {@code true} if {@link #start()} has been called on this stopwatch, and {@link #stop()}
+   *     has not been called since the last call to {@code start()}.
    */
   public boolean isRunning() {
     return isRunning;
@@ -125,6 +134,9 @@ private long elapsedNanos() {
    * <p>It is generally not a good idea to use an ambiguous, unitless {@code long} to represent
    * elapsed time. Therefore, we recommend using {@link #elapsed()} instead, which returns a
    * strongly-typed {@link Duration} instance.
+   *
+   * @param desiredUnit the desired time unit
+   * @return the current elapsed time shown on this stopwatch
    */
   public long elapsed(TimeUnit desiredUnit) {
     return desiredUnit.convert(elapsedNanos(), NANOSECONDS);
@@ -133,6 +145,8 @@ public long elapsed(TimeUnit desiredUnit) {
   /**
    * Returns the current elapsed time shown on this stopwatch as a {@link Duration}. Unlike {@link
    * #elapsed(TimeUnit)}, this method does not lose any precision due to rounding.
+   *
+   * @return the current elapsed time shown on this stopwatch as a {@link Duration}.
    */
   public Duration elapsed() {
     return Duration.ofNanos(elapsedNanos());