docs: use appropriate javadoc url syntax (#77)

Author: y-lakhdar

src/main/java/com/coveo/pushapiclient/ApiUrl.java

@@ -10,8 +10,10 @@
 
 /**
  * Private util class to extract dynamic parts from a API URL Handles extraction of identifiers and
- * platform URL from a source URL. @See https://docs.coveo.com/en/1546#push-api-url
- * https://docs.coveo.com/en/3295#stream-api-url
+ * platform URL from a source URL.
+ *
+ * @see <a href="https://docs.coveo.com/en/1546#push-api-url">Push API url</a>
+ * @see <a href="https://docs.coveo.com/en/3295#stream-api-url">Stream API url</a>
  */
 class ApiUrl {
   private final String organizationId;

src/main/java/com/coveo/pushapiclient/BatchIdentity.java

@@ -4,7 +4,9 @@
 import com.google.gson.JsonObject;
 import java.util.List;
 
-/** See [Manage Batches of Security Identities](https://docs.coveo.com/en/55) */
+/**
+ * @see <a href="https://docs.coveo.com/en/55">Manage Batches of Security Identities</a>
+ */
 public class BatchIdentity {
 
   private List<SecurityIdentityModel> members;

src/main/java/com/coveo/pushapiclient/BatchIdentityRecord.java

@@ -2,7 +2,9 @@
 
 import com.google.gson.JsonObject;
 
-/** See [BatchIdentityBody](https://docs.coveo.com/en/139#batchidentitybody) */
+/**
+ * @see <a href="https://docs.coveo.com/en/139#batchidentitybody">BatchIdentityBody]</a>
+ */
 public class BatchIdentityRecord {
 
   private JsonObject[] members;

src/main/java/com/coveo/pushapiclient/BatchUpdate.java

@@ -4,7 +4,9 @@
 import java.util.List;
 import java.util.Objects;
 
-/** See [Manage Batches of Items in a Push Source](https://docs.coveo.com/en/90) */
+/**
+ * @see <a href="https://docs.coveo.com/en/90">Manage Batches of Items in a Push Source</a>
+ */
 public class BatchUpdate {
 
   private final List<DocumentBuilder> addOrUpdate;

src/main/java/com/coveo/pushapiclient/BatchUpdateRecord.java

@@ -3,7 +3,9 @@
 import com.google.gson.JsonObject;
 import java.util.Arrays;
 
-/** See [BatchDocumentBody](https://docs.coveo.com/en/75/#batchdocumentbody) */
+/**
+ * @see <a href="https://docs.coveo.com/en/75/#batchdocumentbody">BatchDocumentBody</a>
+ */
 public class BatchUpdateRecord {
 
   private final JsonObject[] addOrUpdate;

src/main/java/com/coveo/pushapiclient/CatalogSource.java

@@ -15,7 +15,8 @@ public class CatalogSource implements StreamEnabledSource {
    * @param platformClient
    * @param name The name of the source to create
    * @param sourceVisibility The security option that should be applied to the content of the
-   *     source. See [Content Security](https://docs.coveo.com/en/1779).
+   *     source.
+   * @see <a href="https://docs.coveo.com/en/1779">Content Security</a>
    * @return
    * @throws IOException
    * @throws InterruptedException

src/main/java/com/coveo/pushapiclient/DocumentBuilder.java

@@ -29,8 +29,10 @@ public class DocumentBuilder {
   private final Document document;
 
   /**
-   * @param uri the URI of the document. See {@link Document#uri}
-   * @param title the title of the document. See {@link Document#title}
+   * @param uri the URI of the document.
+   * @see {@link Document#uri}
+   * @param title the title of the document.
+   * @see {@link Document#title}
    */
   public DocumentBuilder(String uri, String title) {
     this.document = new Document();
@@ -43,8 +45,9 @@ public Document getDocument() {
   }
 
   /**
-   * Set the data of the document. See {@link Document#data}
+   * Set the data of the document.
    *
+   * @see {@link Document#data}
    * @param data
    * @return
    */
@@ -54,8 +57,9 @@ public DocumentBuilder withData(String data) {
   }
 
   /**
-   * Set the date of the document. See {@link Document#date}
+   * Set the date of the document.
    *
+   * @see {@link Document#date}
    * @param date
    * @return
    */
@@ -66,8 +70,9 @@ public DocumentBuilder withDate(String date) {
   }
 
   /**
-   * Set the date of the document. See {@link Document#date}
+   * Set the date of the document.
    *
+   * @see {@link Document#date}
    * @param date
    * @return
    */
@@ -78,8 +83,9 @@ public DocumentBuilder withDate(Long date) {
   }
 
   /**
-   * Set the date of the document. See {@link Document#date}
+   * Set the date of the document.
    *
+   * @see {@link Document#date}
    * @param date
    * @return
    */
@@ -90,8 +96,9 @@ public DocumentBuilder withDate(Date date) {
   }
 
   /**
-   * Set the date of the document. See {@link Document#date}
+   * Set the date of the document.
    *
+   * @see {@link Document#date}
    * @param date
    * @return
    */
@@ -101,8 +108,9 @@ public DocumentBuilder withDate(DateTime date) {
   }
 
   /**
-   * Set the modified date of the document. See {@link Document#modifiedDate}
+   * Set the modified date of the document.
    *
+   * @see {@link Document#modifiedDate}
    * @param date
    * @return
    */
@@ -113,8 +121,9 @@ public DocumentBuilder withModifiedDate(String date) {
   }
 
   /**
-   * Set the modified date of the document. See {@link Document#modifiedDate}
+   * Set the modified date of the document.
    *
+   * @see {@link Document#modifiedDate}
    * @param date
    * @return
    */
@@ -125,8 +134,9 @@ public DocumentBuilder withModifiedDate(Long date) {
   }
 
   /**
-   * Set the modified date of the document. See {@link Document#modifiedDate}
+   * Set the modified date of the document.
    *
+   * @see {@link Document#modifiedDate}
    * @param date
    * @return
    */
@@ -136,8 +146,9 @@ public DocumentBuilder withModifiedDate(DateTime date) {
   }
 
   /**
-   * Set the modified date of the document. See {@link Document#modifiedDate}
+   * Set the modified date of the document.
    *
+   * @see {@link Document#modifiedDate}
    * @param date
    * @return
    */
@@ -148,8 +159,9 @@ public DocumentBuilder withModifiedDate(Date date) {
   }
 
   /**
-   * Set the permanentID of the document. See {@link Document#permanentId}
+   * Set the permanentID of the document.
    *
+   * @see {@link Document#permanentId}
    * @param permanentId
    * @return
    */
@@ -159,9 +171,9 @@ public DocumentBuilder withPermanentId(String permanentId) {
   }
 
   /**
-   * Set the base64 encoded, compressed binary data of the document. See {@link
-   * Document#compressedBinaryData}
+   * Set the base64 encoded, compressed binary data of the document.
    *
+   * @see {@link Document#compressedBinaryData}
    * @param compressedBinaryData
    * @return
    */
@@ -171,9 +183,9 @@ public DocumentBuilder withCompressedBinaryData(CompressedBinaryData compressedB
   }
 
   /**
-   * Set the file container file ID for the compressed binary data of the document. See {@link
-   * Document#compressedBinaryDataFileId}
+   * Set the file container file ID for the compressed binary data of the document.
    *
+   * @see {@link Document#compressedBinaryDataFileId}
    * @param compressedBinaryDataFileId
    * @return
    */
@@ -183,8 +195,9 @@ public DocumentBuilder withCompressedBinaryDataFileId(String compressedBinaryDat
   }
 
   /**
-   * Set the file extension on the document. See {@link Document#fileExtension}
+   * Set the file extension on the document.
    *
+   * @see {@link Document#fileExtension}
    * @param fileExtension
    * @return
    */
@@ -195,8 +208,9 @@ public DocumentBuilder withFileExtension(String fileExtension) {
   }
 
   /**
-   * Set the parentID on the document. See {@link Document#parentId}
+   * Set the parentID on the document.
    *
+   * @see {@link Document#parentId}
    * @param parentID
    * @return
    */
@@ -206,8 +220,9 @@ public DocumentBuilder withParentID(String parentID) {
   }
 
   /**
-   * Set the clickableURI on the document. See {@link Document#clickableUri}
+   * Set the clickableURI on the document.
    *
+   * @see {@link Document#clickableUri}
    * @param clickableUri
    * @return
    */
@@ -217,8 +232,9 @@ public DocumentBuilder withClickableUri(String clickableUri) {
   }
 
   /**
-   * Set the author on the document. See {@link Document#author}
+   * Set the author on the document.
    *
+   * @see {@link Document#author}
    * @param author
    * @return
    */
@@ -228,8 +244,9 @@ public DocumentBuilder withAuthor(String author) {
   }
 
   /**
-   * Add a single metadata key and value pair on the document. See {@link Document#metadata}
+   * Add a single metadata key and value pair on the document.
    *
+   * @see {@link Document#metadata}
    * @param key
    * @param metadataValue
    * @return
@@ -240,8 +257,9 @@ public DocumentBuilder withMetadataValue(String key, String metadataValue) {
   }
 
   /**
-   * Add a single metadata key and value pair on the document. See {@link Document#metadata}
+   * Add a single metadata key and value pair on the document.
    *
+   * @see {@link Document#metadata}
    * @param key
    * @param metadataValue
    * @return
@@ -252,8 +270,9 @@ public DocumentBuilder withMetadataValue(String key, String[] metadataValue) {
   }
 
   /**
-   * Add a single metadata key and value pair on the document. See {@link Document#metadata}
+   * Add a single metadata key and value pair on the document.
    *
+   * @see {@link Document#metadata}
    * @param key
    * @param metadataValue
    * @return
@@ -264,8 +283,9 @@ public DocumentBuilder withMetadataValue(String key, Integer metadataValue) {
   }
 
   /**
-   * Add a single metadata key and value pair on the document. See {@link Document#metadata}
+   * Add a single metadata key and value pair on the document.
    *
+   * @see {@link Document#metadata}
    * @param key
    * @param metadataValue
    * @return
@@ -276,8 +296,9 @@ public DocumentBuilder withMetadataValue(String key, Integer[] metadataValue) {
   }
 
   /**
-   * Set metadata on the document. See {@link Document#metadata}
+   * Set metadata on the document.
    *
+   * @see {@link Document#metadata}
    * @param metadata
    * @return
    */
@@ -287,8 +308,9 @@ public DocumentBuilder withMetadata(Map<String, Object> metadata) {
   }
 
   /**
-   * Set allowed identities on the document. See {@link Document#permissions}
+   * Set allowed identities on the document.
    *
+   * @see {@link Document#permissions}
    * @param allowedPermissions
    * @return
    */
@@ -298,8 +320,9 @@ public DocumentBuilder withAllowedPermissions(SecurityIdentityBuilder allowedPer
   }
 
   /**
-   * Set denied identities on the document. See {@link Document#permissions}
+   * Set denied identities on the document.
    *
+   * @see {@link Document#permissions}
    * @param deniedPermissions
    * @return
    */
@@ -309,8 +332,9 @@ public DocumentBuilder withDeniedPermissions(SecurityIdentityBuilder deniedPermi
   }
 
   /**
-   * Set allowAnonymous for permissions on the document. See {@link Document#permissions}
+   * Set allowAnonymous for permissions on the document.
    *
+   * @see {@link Document#permissions}
    * @param allowAnonymous
    * @return
    */
@@ -320,8 +344,9 @@ public DocumentBuilder withAllowAnonymousUsers(Boolean allowAnonymous) {
   }
 
   /**
-   * Set the fully built out DocumentPermissions array. See {@Link Document#permissions}
+   * Set the fully built out DocumentPermissions array.
    *
+   * @see {@Link Document#permissions}
    * @param documentPermissions
    * @return
    */
@@ -383,7 +408,8 @@ private void validateReservedMetadataKeyNames(String key) {
     if (reservedKeynames.contains(key)) {
       throw new RuntimeException(
           String.format(
-              "Cannot use %s as a metadata key: It is a reserved keynames. See https://docs.coveo.com/en/78/index-content/push-api-reference#json-document-reserved-key-names",
+              "Cannot use %s as a metadata key: It is a reserved keynames. See"
+                  + " https://docs.coveo.com/en/78/index-content/push-api-reference#json-document-reserved-key-names",
               key));
     }
   }

src/main/java/com/coveo/pushapiclient/FileContainer.java

@@ -2,7 +2,9 @@
 
 import java.util.Map;
 
-/** See [Creating a FileContainer](https://docs.coveo.com/en/43) */
+/**
+ * @see <a href="https://docs.coveo.com/en/43">Creating a FileContainer</a>
+ */
 public class FileContainer {
   public String uploadUri;
   public String fileId;