Add Javadocs, reduce visibility of a few annotations, rename OptimizationObjectives, rename SmoothieMapBuilder.minExpectedSize to minPeakSize, add signing plugin to gradle build

Author: leventov

build.gradle

@@ -13,6 +13,7 @@ buildscript {
 plugins {
     id 'java-library'
     id 'maven-publish'
+    id 'signing'
 
     id 'checkstyle'
     id 'de.thetaphi.forbiddenapis' version '2.6'
@@ -200,6 +201,24 @@ task sourcesJar(type: Jar, dependsOn: classes) {
     from sourceSets.main.allSource
 }
 
+javadoc {
+    options {
+        links 'http://docs.oracle.com/javase/8/docs/api/'
+        tags = [
+                'apiNote:a:API Note:',
+                'implSpec:a:Implementation Requirements:',
+                'implNote:a:Implementation Note:',
+                'param',
+                'return',
+                'throws',
+                'since',
+                'version',
+                'serialData',
+                'see'
+        ]
+    }
+}
+
 task javadocJar(type: Jar) {
     classifier 'javadoc'
     from javadoc

src/main/java/io/timeandspace/collect/Equivalence.java

@@ -26,7 +26,7 @@
  * A strategy for determining whether two instances are considered equivalent.
  *
  * <p>This class is inspired and very similar to
- * <a href="http://docs.guava-libraries.googlecode.com/git-history/release/javadoc/com/google/common/base/Equivalence.html">
+ * <a href="https://guava.dev/releases/27.1-jre/api/docs/com/google/common/base/Equivalence.html">
  * Guava's {@code Equivalence}</a>, with one notable difference: this {@code Equivalence} forces
  * the actual implementation to override {@link #equals(Object)} and {@link #hashCode()}. Notice
  * these are {@code Equivalence}'s own equals and hashCode, not the strategy

src/main/java/io/timeandspace/collect/map/KeyValue.java

@@ -18,7 +18,7 @@
 
 /**
  * Defines a simple key-value pair. The difference between this interface and {@link
- * java.util.Map.Entry} is that this interface doesn't specify {@link #equals} and {@link #hashCode}
+ * java.util.Map.Entry} is that this interface doesn't specify {@link Object#equals} and {@link Object#hashCode}
  * and whether they should depend on key's and value's equivalence and hash codes at all.
  * KeyValue also doesn't have an equivalent of {@link java.util.Map.Entry}'s {@code setValue()}
  * method.

src/main/java/io/timeandspace/collect/map/ObjObjMap.java

@@ -31,6 +31,25 @@
 import java.util.function.BiPredicate;
 import java.util.function.Function;
 
+/**
+ * An extension of the {@link Map} interface. Notable additions and differences:
+ * <ul>
+ *     <li>{@code null} keys and values are explicitly prohibited. Attempt to query nulls via
+ *     methods like {@link #get(Object)} or {@link #containsValue(Object)} are specified to throw
+ *     a {@link NullPointerException} as well. In the {@link Map} interface, both aspects (rejecting
+ *     nulls for storage and rejecting null queries) are optional.</li>
+ *     <li>The notion of non-standard key and value equivalences is formalized in {@link
+ *     #keyEquivalence()} and {@link #valueEquivalence()} methods.</li>
+ *     <li>{@link #sizeAsLong()} returns the exact size of the map if it exceeds {@link
+ *     Integer#MAX_VALUE}.</li>
+ *     <li>{@link #containsEntry(Object, Object)}</li>
+ *     <li>{@link #getInternalKey} allows to use the map as the vehicle for key interning.</li>
+ *     <li>{@link #forEachWhile(BiPredicate)}</li>
+ *     <li>{@link #removeIf(BiPredicate)}</li>
+ * </ul>
+ * @param <K> the type of keys maintained by this map
+ * @param <V> the type of mapped values
+ */
 public interface ObjObjMap<K, V> extends Map<K, V> {
 
     /**
@@ -117,8 +136,10 @@ default long mappingCount() {
      * <p>This method could be used to deduplicate objects in the application, to reduce the memory
      * footprint and make the application to conform to the "most objects die young" hypothesis that
      * most GC algorithms are optimized for. This method is functionally similar to {@link
-     * String#intern()} and Guava's Interner, but allows to piggy-back a map data structure which
-     * may already exist in an application.
+     * String#intern()} and Guava's <a
+     * href="https://guava.dev/releases/28.0-jre/api/docs/com/google/common/collect/Interner.html">
+     * Interner</a>, but allows to piggy-back a map data structure which may already exist in an
+     * application.
      *
      * <p>{@link #keySet()}.{@link ObjSet#getInternal(Object) getInternal(key)} delegates to this
      * method.

src/main/java/io/timeandspace/collect/map/package-info.java

@@ -15,13 +15,11 @@
  */
 
 
-/**
- *
- */
 @CheckReturnValue
-@DefaultQualifier(NonNull.class)
+@DefaultQualifier(value = NonNull.class, locations = TypeUseLocation.ALL)
 package io.timeandspace.collect.map;
 
 import com.google.errorprone.annotations.CheckReturnValue;
 import org.checkerframework.checker.nullness.qual.NonNull;
-import org.checkerframework.framework.qual.DefaultQualifier;
+import org.checkerframework.framework.qual.DefaultQualifier;
+import org.checkerframework.framework.qual.TypeUseLocation;

src/main/java/io/timeandspace/smoothie/BarelyCalled.java

@@ -29,5 +29,5 @@
  */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.SOURCE)
-public @interface BarelyCalled {
+@interface BarelyCalled {
 }

src/main/java/io/timeandspace/smoothie/CompileTimeConstant.java

@@ -32,5 +32,5 @@
  */
 @Retention(RetentionPolicy.SOURCE)
 @Target(ElementType.FIELD)
-public @interface CompileTimeConstant {
+@interface CompileTimeConstant {
 }

src/main/java/io/timeandspace/smoothie/OptimizationObjective.java

@@ -16,7 +16,37 @@
 
 package io.timeandspace.smoothie;
 
+/**
+ * OptimizationObjectives correspond to {@link SmoothieMap}'s <i>modes of operation</i> which could
+ * be configured via {@link SmoothieMapBuilder#optimizeFor} method.
+ */
 public enum OptimizationObjective {
-    ALLOCATION_RATE,
-    MEMORY_FOOTPRINT
+    /**
+     * In the "low-garbage" mode, {@link SmoothieMap} generates very little garbage (that is, heap
+     * objects that  later become unreachable and need to be swept by the GC), either during the
+     * growth phase or the shrinkage phase (when a map reduces in size after the peak growth).
+     *
+     * @implSpec Configuring {@link SmoothieMapBuilder#optimizeFor
+     * smoothieMapBuilder.optimizeFor(LOW_GARBAGE)} includes <i>not</i> {@linkplain
+     * SmoothieMapBuilder#allocateIntermediateCapacitySegments(boolean) allocating
+     * intermediate-capacity segments} (nor, consequently, {@linkplain
+     * SmoothieMapBuilder#splitBetweenTwoNewSegments(boolean) splitting between two new segments})
+     * and <i>not</i> {@linkplain SmoothieMapBuilder#doShrink(boolean) shrinking SmoothieMap
+     * automatically} when it reduces in size.
+     */
+    LOW_GARBAGE,
+
+    /**
+     * In the "footprint" mode, {@link SmoothieMap} has the lowest possible footprint per entry and
+     * the lowest variability of the footprint at different SmoothieMap's sizes.
+     *
+     * @implSpec Configuring {@link SmoothieMapBuilder#optimizeFor
+     * smoothieMapBuilder.optimizeFor(FOOTPRINT)} includes {@linkplain
+     * SmoothieMapBuilder#allocateIntermediateCapacitySegments(boolean) allocating
+     * intermediate-capacity segments}, {@linkplain
+     * SmoothieMapBuilder#splitBetweenTwoNewSegments(boolean) splitting between two new segments},
+     * and {@linkplain SmoothieMapBuilder#doShrink(boolean) automatic shrinking} when a SmoothieMap
+     * reduces in size.
+     */
+    FOOTPRINT
 }

src/main/java/io/timeandspace/smoothie/RarelyCalledAmortizedPerSegment.java

@@ -28,5 +28,5 @@
  *
  * @see AmortizedPerSegment
  */
-public @interface RarelyCalledAmortizedPerSegment {
+@interface RarelyCalledAmortizedPerSegment {
 }