Javadocs polish (#122)

src/main/java/info/freelibrary/iiif/presentation/v3/Annotation.java

@@ -6,6 +6,7 @@
 import java.net.URI;
 import java.util.ArrayList;
 import java.util.Arrays;
+import java.util.Comparator;
 import java.util.List;
 import java.util.Map;
 import java.util.Objects;
@@ -28,7 +29,6 @@
 import info.freelibrary.iiif.presentation.v3.properties.behaviors.ResourceBehavior;
 import info.freelibrary.iiif.presentation.v3.properties.selectors.MediaFragmentSelector;
 import info.freelibrary.iiif.presentation.v3.properties.selectors.Selector;
-import info.freelibrary.iiif.presentation.v3.utils.ContentResourceComparator;
 import info.freelibrary.iiif.presentation.v3.utils.JsonKeys;
 import info.freelibrary.iiif.presentation.v3.utils.MessageCodes;
 
@@ -488,4 +488,43 @@ private void deserializeContentMap(final Map<?, ?> aMap) {
                 break;
         }
     }
+
+    /**
+     * A comparator that returns the sort order of the {@link Annotation} properties.
+     */
+    static class ContentResourceComparator implements Comparator<String> {
+
+        /**
+         * Defines the desired content resource sort order.
+         */
+        private static final String[] KEYS = { JsonKeys.ID, JsonKeys.TYPE, JsonKeys.DEFAULT, JsonKeys.ITEMS,
+            JsonKeys.FORMAT, JsonKeys.HEIGHT, JsonKeys.WIDTH, JsonKeys.LABEL, JsonKeys.SERVICE };
+
+        @Override
+        public int compare(final String aFirstKey, final String aSecondKey) {
+            final int firstKeyIndex = getIndex(KEYS, aFirstKey);
+            final int secondKeyIndex = getIndex(KEYS, aSecondKey);
+
+            return ((Integer) firstKeyIndex).compareTo(secondKeyIndex);
+        }
+
+        /**
+         * Gets a key index position.
+         *
+         * @param aKeyArray An array of keys
+         * @param aKey A particular key
+         * @return The index position of the particular key in the array or -1 if the key isn't found in the array
+         */
+        private int getIndex(final String[] aKeyArray, final String aKey) {
+            Objects.requireNonNull(aKey);
+
+            for (int index = 0; index < aKeyArray.length; index++) {
+                if (aKey.equals(aKeyArray[index])) {
+                    return index;
+                }
+            }
+
+            return -1;
+        }
+    }
 }

src/main/java/info/freelibrary/iiif/presentation/v3/AnnotationPage.java

@@ -32,7 +32,7 @@
 import info.freelibrary.iiif.presentation.v3.utils.MessageCodes;
 
 /**
- * A collection of {@link Annotation}(s) included in the items property from the Canvas.
+ * A collection of {@link Annotation}(s) included in the items property of the Canvas (and whose target is that Canvas).
  */
 @SuppressWarnings(PMD.GOD_CLASS)
 public class AnnotationPage<T extends Annotation<T>> extends AbstractResource<AnnotationPage<T>> // NOPMD

src/main/java/info/freelibrary/iiif/presentation/v3/Collection.java

@@ -4,7 +4,6 @@
 import java.net.URI;
 import java.util.ArrayList;
 import java.util.Arrays;
-import java.util.Collections;
 import java.util.List;
 import java.util.Objects;
 import java.util.Optional;
@@ -497,7 +496,7 @@ public static Collection fromString(final String aJsonString) {
     }
 
     /**
-     * A wrapper for {@link Manifest}s and/or {@link Collections} embedded in, or referenced from, a collection.
+     * A wrapper for {@link Manifest}s and/or {@link Collection}s embedded in, or referenced from, a {@link Collection}.
      */
     @JsonInclude(Include.NON_EMPTY)
     @JsonPropertyOrder({ JsonKeys.ID, JsonKeys.TYPE, JsonKeys.LABEL, JsonKeys.THUMBNAIL, JsonKeys.NAV_DATE })

src/main/java/info/freelibrary/iiif/presentation/v3/ContentOutOfBoundsException.java

@@ -5,7 +5,8 @@
 import info.freelibrary.util.I18nRuntimeException;
 
 /**
- * An exception thrown when a canvas is painted with a content resource that doesn't fit within the canvas bounds.
+ * An exception thrown when attempting to paint a {@link Canvas} (or a region of one) with a {@link ContentResource}
+ * that doesn't fit within the canvas (or region) bounds.
  */
 public class ContentOutOfBoundsException extends I18nRuntimeException {
 

src/main/java/info/freelibrary/iiif/presentation/v3/OtherContent.java

@@ -18,8 +18,9 @@
 import io.vertx.core.json.JsonObject;
 
 /**
- * A content resource for other types of resources than those described by the IIIF specification. The format returned
- * by this class is always JSON. Look in the JsonObject if the wrapped context has a format in its JSON representation.
+ * A content resource for other types of resources than those described by the
+ * <a href="http://iiif.io/api/presentation/3/">IIIF Presentation API</a> specification. The format returned by this
+ * class is always JSON. Look in the {@link JsonObject} if the wrapped context has a format in its JSON representation.
  */
 @JsonPropertyOrder({ JsonKeys.ID, JsonKeys.TYPE })
 public class OtherContent implements AnnotationBody<OtherContent>, ContentResource<OtherContent> {

src/main/java/info/freelibrary/iiif/presentation/v3/SelectorOutOfBoundsException.java

@@ -5,7 +5,7 @@
 import info.freelibrary.util.I18nRuntimeException;
 
 /**
- * An exception thrown when a non-existent fragment of a resource is referenced.
+ * An exception thrown when attempting to paint a non-existent region of a {@link Canvas}.
  */
 public class SelectorOutOfBoundsException extends I18nRuntimeException {
 

src/main/java/info/freelibrary/iiif/presentation/v3/ids/MinterFactory.java

@@ -10,7 +10,7 @@
 import info.freelibrary.iiif.presentation.v3.utils.MessageCodes;
 
 /**
- * A factory that returns a minter used in automatically creating IDs for a manifest.
+ * A factory that returns a minter used in automatically creating IDs for resources related to a manifest.
  */
 public final class MinterFactory {
 

src/main/java/info/freelibrary/iiif/presentation/v3/ids/package-info.java

@@ -1,5 +1,8 @@
 /**
- * Identifier factories that can be used to generate IDs for manifest components.
+ * Identifier factories that are useful for automatically generating unique IDs for various types of resources related
+ * to a given {@link Manifest}.
  */
 
 package info.freelibrary.iiif.presentation.v3.ids;
+
+import info.freelibrary.iiif.presentation.v3.Manifest;

src/main/java/info/freelibrary/iiif/presentation/v3/package-info.java

@@ -1,5 +1,5 @@
 /**
- * Classes used to create and manipulate manifests and collection documents.
+ * Classes used to create and manipulate {@link Manifest}s and {@link Collection}s.
  */
 
 package info.freelibrary.iiif.presentation.v3;

src/main/java/info/freelibrary/iiif/presentation/v3/properties/behaviors/CanvasBehavior.java

@@ -6,12 +6,13 @@
 import info.freelibrary.util.Logger;
 import info.freelibrary.util.LoggerFactory;
 
+import info.freelibrary.iiif.presentation.v3.Canvas;
 import info.freelibrary.iiif.presentation.v3.ResourceTypes;
 import info.freelibrary.iiif.presentation.v3.properties.Behavior;
 import info.freelibrary.iiif.presentation.v3.utils.MessageCodes;
 
 /**
- * The behaviors available to canvases.
+ * The behaviors attributable to {@link Canvas}es.
  */
 public enum CanvasBehavior implements Behavior {
 

src/main/java/info/freelibrary/iiif/presentation/v3/properties/behaviors/CollectionBehavior.java

@@ -6,12 +6,13 @@
 import info.freelibrary.util.Logger;
 import info.freelibrary.util.LoggerFactory;
 
+import info.freelibrary.iiif.presentation.v3.Collection;
 import info.freelibrary.iiif.presentation.v3.ResourceTypes;
 import info.freelibrary.iiif.presentation.v3.properties.Behavior;
 import info.freelibrary.iiif.presentation.v3.utils.MessageCodes;
 
 /**
- * The behaviors available to the collections.
+ * The behaviors attributable to {@link Collection}s.
  */
 public enum CollectionBehavior implements Behavior {
 

src/main/java/info/freelibrary/iiif/presentation/v3/properties/behaviors/ManifestBehavior.java

@@ -6,12 +6,13 @@
 import info.freelibrary.util.Logger;
 import info.freelibrary.util.LoggerFactory;
 
+import info.freelibrary.iiif.presentation.v3.Manifest;
 import info.freelibrary.iiif.presentation.v3.ResourceTypes;
 import info.freelibrary.iiif.presentation.v3.properties.Behavior;
 import info.freelibrary.iiif.presentation.v3.utils.MessageCodes;
 
 /**
- * The behaviors available to manifests.
+ * The behaviors attributable to {@link Manifest}s.
  */
 public enum ManifestBehavior implements Behavior {
 

src/main/java/info/freelibrary/iiif/presentation/v3/properties/behaviors/RangeBehavior.java

@@ -6,12 +6,13 @@
 import info.freelibrary.util.Logger;
 import info.freelibrary.util.LoggerFactory;
 
+import info.freelibrary.iiif.presentation.v3.Range;
 import info.freelibrary.iiif.presentation.v3.ResourceTypes;
 import info.freelibrary.iiif.presentation.v3.properties.Behavior;
 import info.freelibrary.iiif.presentation.v3.utils.MessageCodes;
 
 /**
- * The behaviors available to ranges.
+ * The behaviors attributable to {@link Range}s.
  */
 public enum RangeBehavior implements Behavior {
 

src/main/java/info/freelibrary/iiif/presentation/v3/properties/behaviors/ResourceBehavior.java

@@ -8,11 +8,12 @@
 import info.freelibrary.util.Logger;
 import info.freelibrary.util.LoggerFactory;
 
+import info.freelibrary.iiif.presentation.v3.Resource;
 import info.freelibrary.iiif.presentation.v3.properties.Behavior;
 import info.freelibrary.iiif.presentation.v3.utils.MessageCodes;
 
 /**
- * The behaviors available to resources.
+ * The behaviors attributable to {@link Resource}s.
  */
 public enum ResourceBehavior implements Behavior {
 

src/main/java/info/freelibrary/iiif/presentation/v3/properties/selectors/ImageApiSelector.java

@@ -8,7 +8,7 @@
 import info.freelibrary.iiif.presentation.v3.utils.MessageCodes;
 
 /**
- * A selector for IIIF Image APIs.
+ * A selector for <a href="https://iiif.io/api/image/">IIIF Image API</a>s.
  */
 public class ImageApiSelector implements Selector {
 

src/main/java/info/freelibrary/iiif/presentation/v3/properties/selectors/MediaFragmentSelector.java

@@ -19,11 +19,13 @@
 import info.freelibrary.util.Logger;
 import info.freelibrary.util.LoggerFactory;
 
+import info.freelibrary.iiif.presentation.v3.Canvas;
 import info.freelibrary.iiif.presentation.v3.utils.URIs;
 import info.freelibrary.iiif.presentation.v3.utils.MessageCodes;
 
 /**
- * A media fragment selector selects a region of interest in a resource with spatial and/or temporal dimensions.
+ * A media fragment selector selects a region of interest in a resource with spatial and/or temporal dimensions
+ * (typically a {@link Canvas}).
  */
 public class MediaFragmentSelector implements FragmentSelector {
 

src/main/java/info/freelibrary/iiif/presentation/v3/properties/selectors/package-info.java

@@ -1,5 +1,8 @@
 /**
- * Classes supporting the use of different annotation selectors.
+ * Classes supporting the use of <a href="https://www.w3.org/TR/annotation-model/#selectors">selectors</a> for
+ * annotating segments of resources (typically {@link Canvas}es).
  */
 
 package info.freelibrary.iiif.presentation.v3.properties.selectors;
+
+import info.freelibrary.iiif.presentation.v3.Canvas;

src/main/java/info/freelibrary/iiif/presentation/v3/services/GeoJSONService.java

@@ -10,14 +10,14 @@
 import info.freelibrary.iiif.presentation.v3.utils.JsonKeys;
 
 /**
- * An external service that provides GeoJSON information.
+ * An external service that provides <a href="http://geojson.org/">GeoJSON</a> information.
  */
 public class GeoJSONService extends AbstractService<GeoJSONService> implements Service<GeoJSONService> {
 
     /**
-     * Creates a GeoJSON service.
+     * Creates a <a href="https://iiif.io/api/annex/services/#geojson">GeoJSON service</a>.
      *
-     * @param aID The ID of the item to retrieve GeoJSON about
+     * @param aID The ID of the item to retrieve GeoJSON information about
      */
     public GeoJSONService(final URI aID) {
         super();

src/main/java/info/freelibrary/iiif/presentation/v3/services/PhysicalDimsService.java

@@ -11,7 +11,8 @@
 import info.freelibrary.iiif.presentation.v3.utils.JsonKeys;
 
 /**
- * A physical dimensions service that provides information useful for rulers, etc.
+ * A <a href="https://iiif.io/api/annex/services/#physical-dimensions">physical dimensions service</a> that provides
+ * information useful for rulers, etc.
  */
 public class PhysicalDimsService extends AbstractService<PhysicalDimsService> implements Service<PhysicalDimsService> {
 

src/main/java/info/freelibrary/iiif/presentation/v3/services/auth/package-info.java

@@ -1,5 +1,6 @@
 /**
- * Classes providing information about IIIF Authentication related services.
+ * Classes providing information about services related to the <a href="https://iiif.io/api/auth/">IIIF Authentication
+ * API</a>s.
  */
 
 package info.freelibrary.iiif.presentation.v3.services.auth;

src/main/java/info/freelibrary/iiif/presentation/v3/services/image/ImageAPI.java

@@ -7,7 +7,7 @@
 import info.freelibrary.iiif.presentation.v3.utils.MessageCodes;
 
 /**
- * Constants related to the IIIF Image API.
+ * Constants related to the <a href="https://iiif.io/api/image/">IIIF Image API</a>.
  */
 public interface ImageAPI {
 

src/main/java/info/freelibrary/iiif/presentation/v3/services/image/ImageService2.java

@@ -21,7 +21,8 @@
 import info.freelibrary.iiif.presentation.v3.utils.MessageCodes;
 
 /**
- * A service that will return information about a particular image via IIIF Image API 2.
+ * A service that will return information about a particular image via <a href="https://iiif.io/api/image/2/">IIIF Image
+ * API 2</a>.
  */
 public class ImageService2 extends AbstractImageService<ImageService2> implements ImageService<ImageService2> {
 

src/main/java/info/freelibrary/iiif/presentation/v3/services/image/ImageService3.java

@@ -21,7 +21,8 @@
 import info.freelibrary.iiif.presentation.v3.utils.MessageCodes;
 
 /**
- * A service that will return information about a particular image via IIIF Image API 3.
+ * A service that will return information about a particular image via <a href="https://iiif.io/api/image/3/">IIIF Image
+ * API 3</a>.
  */
 public class ImageService3 extends AbstractImageService<ImageService3> implements ImageService<ImageService3> {
 

src/main/java/info/freelibrary/iiif/presentation/v3/services/image/package-info.java

@@ -1,5 +1,5 @@
 /**
- * Classes providing information about IIIF Image related services.
+ * Classes providing information about services related to the <a href="https://iiif.io/api/image/">IIIF Image API</a>s.
  */
 
 package info.freelibrary.iiif.presentation.v3.services.image;

src/main/java/info/freelibrary/iiif/presentation/v3/utils/JsonKeys.java

@@ -1,8 +1,11 @@
 
 package info.freelibrary.iiif.presentation.v3.utils;
 
+import info.freelibrary.iiif.presentation.v3.Collection;
+import info.freelibrary.iiif.presentation.v3.Manifest;
+
 /**
- * A constants class for keys used in the JSON serialization of IIIF Presentation manifests and collections.
+ * A constants class for keys used in the JSON serialization of {@link Manifest}s and {@link Collection}s.
  */
 public final class JsonKeys {