Add Javadoc and configure doclint (#65)

pom.xml

@@ -171,6 +171,10 @@
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-javadoc-plugin</artifactId>
         <version>3.6.0</version>
+        <configuration>
+          <quiet>true</quiet>
+          <doclint>all,-missing,-reference</doclint>
+        </configuration>
         <executions>
           <execution>
             <id>attach-javadocs</id>

src/main/java/org/matomo/java/tracking/CustomVariable.java

@@ -18,6 +18,12 @@
 @Deprecated
 public class CustomVariable extends org.matomo.java.tracking.parameters.CustomVariable {
 
+  /**
+   * Instantiates a new custom variable.
+   *
+   * @param key the key of the custom variable (required)
+   * @param value the value of the custom variable (required)
+   */
   public CustomVariable(@NonNull String key, @NonNull String value) {
     super(key, value);
   }

src/main/java/org/matomo/java/tracking/EcommerceItem.java

@@ -18,6 +18,15 @@
 public class EcommerceItem extends org.matomo.java.tracking.parameters.EcommerceItem {
 
 
+  /**
+   * Instantiates a new ecommerce item.
+   *
+   * @param sku      the sku (Stock Keeping Unit) of the item
+   * @param name     the name of the item
+   * @param category the category of the item
+   * @param price    the price of the item
+   * @param quantity the quantity of the item
+   */
   public EcommerceItem(
     String sku, String name, String category,
     Double price, Integer quantity

src/main/java/org/matomo/java/tracking/MatomoRequest.java

@@ -589,7 +589,7 @@ public class MatomoRequest {
    *
    * @param siteId    the id of the website we're tracking a visit/action for
    * @param actionUrl the full URL for the current action
-   * @deprecated Please use {@link #builder()}
+   * @deprecated Please use {@link MatomoRequest#builder()}
    */
   @Deprecated
   public MatomoRequest(int siteId, String actionUrl) {
@@ -673,7 +673,7 @@ public void clearCustomTrackingParameter() {
    * Sets <em>idgoal&#61;0</em> in the request to track an ecommerce interaction:
    * cart update or an ecommerce order.
    *
-   * @deprecated Please use {@link #setGoalId(Integer)} instead
+   * @deprecated Please use {@link MatomoRequest#setGoalId(Integer)} instead
    */
   @Deprecated
   public void enableEcommerce() {
@@ -735,7 +735,7 @@ public String getPageCustomVariable(String key) {
    *
    * @param index the index of the variable to get.  Must be greater than 0
    * @return the variable at the specified key, null if nothing at this index
-   * @deprecated Use {@link #getPageCustomVariables()} instead
+   * @deprecated Use {@link MatomoRequest#getPageCustomVariables()} instead
    */
   @Deprecated
   @Nullable
@@ -757,7 +757,7 @@ private static CustomVariable getCustomVariable(CustomVariables customVariables,
    *
    * @param key   the key of the variable to set
    * @param value the value of the variable to set at the specified key.  A null value will remove this custom variable
-   * @deprecated Use {@link #getPageCustomVariables()} instead
+   * @deprecated Use {@link MatomoRequest#getPageCustomVariables()} instead
    */
   @Deprecated
   public void setPageCustomVariable(@NotNull String key, @Nullable String value) {

src/main/java/org/matomo/java/tracking/parameters/CustomVariable.java

@@ -41,6 +41,12 @@ public class CustomVariable {
   @NonNull
   private String value;
 
+  /**
+   * Instantiates a new custom variable.
+   *
+   * @param key the key of the custom variable (required)
+   * @param value the value of the custom variable (required)
+   */
   public CustomVariable(@NonNull String key, @NonNull String value) {
     this.key = key;
     this.value = value;

src/main/java/org/matomo/java/tracking/parameters/CustomVariables.java

@@ -70,22 +70,46 @@ private static void validateIndex(int index) {
     }
   }
 
+  /**
+   * Returns the custom variable at the given index.
+   *
+   * @param index The index of the custom variable
+   * @return The custom variable at the given index
+   */
   @Nullable
   public CustomVariable get(int index) {
     validateIndex(index);
     return variables.get(index);
   }
 
+  /**
+   * Returns the value of the custom variable with the given key. If there are multiple custom variables with the same
+   * key, the first one is returned. If there is no custom variable with the given key, null is returned.
+   *
+   * @param key The key of the custom variable. Must not be null.
+   * @return The value of the custom variable with the given key. null if there is no variable with the given key.
+   */
   @Nullable
   public String get(@NonNull String key) {
     return variables.values().stream().filter(variable -> variable.getKey().equals(key)).findFirst()
       .map(CustomVariable::getValue).orElse(null);
   }
 
+  /**
+   * Removes the custom variable at the given index. If there is no custom variable at the given index, nothing happens.
+   *
+   * @param index The index of the custom variable to remove. Must be greater than 0.
+   */
   public void remove(int index) {
+    validateIndex(index);
     variables.remove(index);
   }
 
+  /**
+   * Removes the custom variable with the given key. If there is no custom variable with the given key, nothing happens.
+   *
+   * @param key The key of the custom variable to remove. Must not be null.
+   */
   public void remove(@NonNull String key) {
     variables.entrySet().removeIf(entry -> entry.getValue().getKey().equals(key));
   }
@@ -94,6 +118,12 @@ boolean isEmpty() {
     return variables.isEmpty();
   }
 
+  /**
+   * Creates a JSON representation of the custom variables. The format is as follows:
+   * {@code {"1":["key1","value1"],"2":["key2","value2"]}}
+   *
+   * @return A JSON representation of the custom variables
+   */
   @Override
   public String toString() {
     StringBuilder stringBuilder = new StringBuilder("{");

src/main/java/org/matomo/java/tracking/parameters/EcommerceItems.java

@@ -8,6 +8,7 @@
 package org.matomo.java.tracking.parameters;
 
 import lombok.AllArgsConstructor;
+import lombok.Builder;
 import lombok.EqualsAndHashCode;
 import lombok.Getter;
 import lombok.NoArgsConstructor;
@@ -22,6 +23,7 @@
 /**
  * Multiple things that you can buy online.
  */
+@Builder
 @AllArgsConstructor
 @NoArgsConstructor
 @EqualsAndHashCode

src/main/java/org/matomo/java/tracking/parameters/VisitorId.java

@@ -28,7 +28,6 @@ public class VisitorId {
    *
    * <p>Please consider creating a fixed id for each visitor by getting a hash code from e.g. the username and
    * using {@link #fromHash(long)}
-   * <
    *
    * @return A randomly generated visitor id
    */

src/main/java/org/piwik/java/tracking/CustomVariable.java

@@ -21,6 +21,8 @@ public class CustomVariable extends org.matomo.java.tracking.parameters.CustomVa
   /**
    * Instantiates a new custom variable.
    *
+   * @param key   the key of the custom variable (required)
+   * @param value the value of the custom variable (required)
    * @deprecated Use {@link org.matomo.java.tracking.parameters.CustomVariable} instead.
    */
   @Deprecated

src/main/java/org/piwik/java/tracking/EcommerceItem.java

@@ -19,6 +19,11 @@ public class EcommerceItem extends org.matomo.java.tracking.parameters.Ecommerce
   /**
    * Creates a new ecommerce item.
    *
+   * @param sku      the sku (Stock Keeping Unit) of the item.
+   * @param name     the name of the item.
+   * @param category the category of the item.
+   * @param price    the price of the item.
+   * @param quantity the quantity of the item.
    * @deprecated Use {@link org.matomo.java.tracking.parameters.EcommerceItem} instead.
    */
   @Deprecated

src/main/java/org/piwik/java/tracking/PiwikDate.java

@@ -25,7 +25,6 @@ public class PiwikDate extends MatomoDate {
   /**
    * Creates a new date object with the current time.
    *
-   * @author brettcsorba
    * @deprecated Use {@link Instant} instead.
    */
   public PiwikDate() {
@@ -34,7 +33,7 @@ public PiwikDate() {
   /**
    * Creates a new date object with the specified time. The time is specified in milliseconds since the epoch.
    *
-   * @author brettcsorba
+   * @param epochMilli The time in milliseconds since the epoch
    * @deprecated Use {@link Instant} instead.
    */
   public PiwikDate(long epochMilli) {
@@ -44,7 +43,7 @@ public PiwikDate(long epochMilli) {
   /**
    * Sets the time zone for this date object. This is used to convert the date to UTC before sending it to Matomo.
    *
-   * @author brettcsorba
+   * @param zone the time zone to use
    * @deprecated Use {@link ZonedDateTime#toInstant()} instead.
    */
   @Deprecated

src/main/java/org/piwik/java/tracking/PiwikLocale.java

@@ -24,6 +24,7 @@ public class PiwikLocale extends Country {
   /**
    * Creates a new Piwik locale object with the specified locale.
    *
+   * @param locale the locale to use
    * @deprecated Use {@link Country} instead.
    */
   @Deprecated

src/main/java/org/piwik/java/tracking/PiwikTracker.java

@@ -21,6 +21,7 @@ public class PiwikTracker extends MatomoTracker {
   /**
    * Creates a new PiwikTracker instance with the given host URL.
    *
+   * @param hostUrl the host URL of the Matomo server
    * @deprecated Use {@link MatomoTracker} instead.
    */
   @Deprecated
@@ -31,6 +32,8 @@ public PiwikTracker(String hostUrl) {
   /**
    * Creates a new PiwikTracker instance with the given host URL and timeout in milliseconds. Use -1 for no timeout.
    *
+   * @param hostUrl the host URL of the Matomo server
+   * @param timeout the timeout in milliseconds or -1 for no timeout
    * @deprecated Use {@link MatomoTracker} instead.
    */
   @Deprecated
@@ -41,6 +44,9 @@ public PiwikTracker(String hostUrl, int timeout) {
   /**
    * Creates a new PiwikTracker instance with the given host URL and proxy settings.
    *
+   * @param hostUrl the host URL of the Matomo server
+   * @param proxyHost the proxy host
+   * @param proxyPort the proxy port
    * @deprecated Use {@link MatomoTracker} instead.
    */
   @Deprecated
@@ -52,6 +58,10 @@ public PiwikTracker(String hostUrl, String proxyHost, int proxyPort) {
    * Creates a new PiwikTracker instance with the given host URL, proxy settings and timeout in milliseconds. Use -1 for
    * no timeout.
    *
+   * @param hostUrl the host URL of the Matomo server
+   * @param proxyHost the proxy host
+   * @param proxyPort the proxy port
+   * @param timeout the timeout in milliseconds or -1 for no timeout
    * @deprecated Use {@link MatomoTracker} instead.
    */
   @Deprecated

src/main/java/org/piwik/java/tracking/package-info.java

@@ -1,7 +1,6 @@
 /**
  * Piwik Java Tracking API. Renamed to {@link org.matomo.java.tracking} in 3.0.0.
  *
- * @deprecated Use {@link org.matomo.java.tracking} instead.
  */
 
 package org.piwik.java.tracking;