Mostly corrected javadocs

Author: leerho

src/main/java/org/apache/datasketches/theta/CompactSketch.java

@@ -190,49 +190,53 @@ private static CompactSketch wrap(final MemorySegment srcSeg, final long seed, f
     }
     final short seedHash = Util.computeSeedHash(seed);
 
-    if (serVer == 4) {
-      return DirectCompactCompressedSketch.wrapInstance(srcSeg,
-          enforceSeed ? seedHash : (short) extractSeedHash(srcSeg));
-    }
-    else if (serVer == 3) {
-      if (PreambleUtil.isEmptyFlag(srcSeg)) {
-        return EmptyCompactSketch.getHeapInstance(srcSeg);
+    switch (serVer) {
+      case 1: {
+        return ForwardCompatibility.heapify1to3(srcSeg, seedHash);
       }
-      if (otherCheckForSingleItem(srcSeg)) {
-        return SingleItemSketch.heapify(srcSeg, enforceSeed ? seedHash : (short) extractSeedHash(srcSeg));
+      case 2: {
+        return ForwardCompatibility.heapify2to3(srcSeg,
+            enforceSeed ? seedHash : (short) extractSeedHash(srcSeg));
       }
-      //not empty & not singleItem
-      final int flags = extractFlags(srcSeg);
-      final boolean compactFlag = (flags & COMPACT_FLAG_MASK) > 0;
-      if (!compactFlag) {
-        throw new SketchesArgumentException(
-            "Corrupted: COMPACT family sketch image must have compact flag set");
+      case 3: {
+        if (PreambleUtil.isEmptyFlag(srcSeg)) {
+          return EmptyCompactSketch.getHeapInstance(srcSeg);
+        }
+        if (otherCheckForSingleItem(srcSeg)) {
+          return SingleItemSketch.heapify(srcSeg, enforceSeed ? seedHash : (short) extractSeedHash(srcSeg));
+        }
+        //not empty & not singleItem
+        final int flags = extractFlags(srcSeg);
+        final boolean compactFlag = (flags & COMPACT_FLAG_MASK) > 0;
+        if (!compactFlag) {
+          throw new SketchesArgumentException(
+              "Corrupted: COMPACT family sketch image must have compact flag set");
+        }
+        final boolean readOnly = (flags & READ_ONLY_FLAG_MASK) > 0;
+        if (!readOnly) {
+          throw new SketchesArgumentException(
+              "Corrupted: COMPACT family sketch image must have Read-Only flag set");
+        }
+        return DirectCompactSketch.wrapInstance(srcSeg,
+            enforceSeed ? seedHash : (short) extractSeedHash(srcSeg));
       }
-      final boolean readOnly = (flags & READ_ONLY_FLAG_MASK) > 0;
-      if (!readOnly) {
+      case 4: {
+        return DirectCompactCompressedSketch.wrapInstance(srcSeg,
+            enforceSeed ? seedHash : (short) extractSeedHash(srcSeg));
+      }
+      default: {
         throw new SketchesArgumentException(
-            "Corrupted: COMPACT family sketch image must have Read-Only flag set");
+            "Corrupted: Serialization Version " + serVer + " not recognized.");
       }
-      return DirectCompactSketch.wrapInstance(srcSeg,
-          enforceSeed ? seedHash : (short) extractSeedHash(srcSeg));
-    } //end of serVer 3
-    else if (serVer == 1) {
-      return ForwardCompatibility.heapify1to3(srcSeg, seedHash);
-    }
-    else if (serVer == 2) {
-      return ForwardCompatibility.heapify2to3(srcSeg,
-          enforceSeed ? seedHash : (short) extractSeedHash(srcSeg));
     }
-    throw new SketchesArgumentException(
-        "Corrupted: Serialization Version " + serVer + " not recognized.");
   }
 
   /**
    * Wrap takes the sketch image in the given byte array and refers to it directly.
    * There is no data copying onto the java heap.
    * The wrap operation enables fast read-only merging and access to all the public read-only API.
    *
-   * <p>Only "Direct" Serialization Version 3 (i.e, OpenSource) sketches that have
+   * <p>Only "Direct" Serialization Versions 3 and 4 (i.e, OpenSource) sketches that have
    * been explicitly stored as direct sketches can be wrapped.
    * Wrapping earlier serial version sketches will result in a heapify operation.
    * These early versions were never designed to "wrap".</p>
@@ -242,7 +246,7 @@ else if (serVer == 2) {
    * This is actually faster and consumes less overall space.</p>
    *
    * <p>This method checks if the DEFAULT_UPDATE_SEED was used to create the source byte array image.
-   * Note that SerialVersion 1 sketches cannot be checked as they don't have a seedHash field,
+   * Note that SerialVersion 1 (pre-open-source) sketches cannot be checked as they don't have a seedHash field,
    * so the resulting heapified CompactSketch will be given the hash of DEFAULT_UPDATE_SEED.</p>
    *
    * @param bytes a byte array image of a Sketch that was created using the DEFAULT_UPDATE_SEED.
@@ -258,7 +262,7 @@ public static CompactSketch wrap(final byte[] bytes) {
    * There is no data copying onto the java heap.
    * The wrap operation enables fast read-only merging and access to all the public read-only API.
    *
-   * <p>Only "Direct" Serialization Version 3 (i.e, OpenSource) sketches that have
+   * <p>Only "Direct" Serialization Versions 3 and 4 (i.e, OpenSource) sketches that have
    * been explicitly stored as direct sketches can be wrapped.
    * Wrapping earlier serial version sketches will result in a heapify operation.
    * These early versions were never designed to "wrap".</p>
@@ -288,38 +292,46 @@ private static CompactSketch wrap(final byte[] bytes, final long seed, final boo
       throw new SketchesArgumentException("Corrupted: " + family + " is not Compact!");
     }
     final short seedHash = Util.computeSeedHash(seed);
-    if (serVer == 4) {
-      return WrappedCompactCompressedSketch.wrapInstance(bytes, seedHash);
-    } else if (serVer == 3) {
-      final int flags = bytes[FLAGS_BYTE];
-      if ((flags & EMPTY_FLAG_MASK) > 0) {
-        return EmptyCompactSketch.getHeapInstance(MemorySegment.ofArray(bytes));
+
+    switch (serVer) {
+      case 1: {
+        return ForwardCompatibility.heapify1to3(MemorySegment.ofArray(bytes), seedHash);
       }
-      final int preLongs = bytes[PREAMBLE_LONGS_BYTE];
-      if (otherCheckForSingleItem(preLongs, serVer, familyId, flags)) {
-        return SingleItemSketch.heapify(MemorySegment.ofArray(bytes), enforceSeed ? seedHash : getShortLE(bytes, SEED_HASH_SHORT));
+      case 2: {
+        return ForwardCompatibility.heapify2to3(MemorySegment.ofArray(bytes),
+            enforceSeed ? seedHash : getShortLE(bytes, SEED_HASH_SHORT));
       }
-      //not empty & not singleItem
-      final boolean compactFlag = (flags & COMPACT_FLAG_MASK) > 0;
-      if (!compactFlag) {
-        throw new SketchesArgumentException(
-            "Corrupted: COMPACT family sketch image must have compact flag set");
+      case 3: {
+        final int flags = bytes[FLAGS_BYTE];
+        if ((flags & EMPTY_FLAG_MASK) > 0) {
+          return EmptyCompactSketch.getHeapInstance(MemorySegment.ofArray(bytes));
+        }
+        final int preLongs = bytes[PREAMBLE_LONGS_BYTE];
+        if (otherCheckForSingleItem(preLongs, serVer, familyId, flags)) {
+          return SingleItemSketch.heapify(MemorySegment.ofArray(bytes), enforceSeed ? seedHash : getShortLE(bytes, SEED_HASH_SHORT));
+        }
+        //not empty & not singleItem
+        final boolean compactFlag = (flags & COMPACT_FLAG_MASK) > 0;
+        if (!compactFlag) {
+          throw new SketchesArgumentException(
+              "Corrupted: COMPACT family sketch image must have compact flag set");
+        }
+        final boolean readOnly = (flags & READ_ONLY_FLAG_MASK) > 0;
+        if (!readOnly) {
+          throw new SketchesArgumentException(
+              "Corrupted: COMPACT family sketch image must have Read-Only flag set");
+        }
+        return WrappedCompactSketch.wrapInstance(bytes,
+            enforceSeed ? seedHash : getShortLE(bytes, SEED_HASH_SHORT));
+      }
+      case 4: {
+        return WrappedCompactCompressedSketch.wrapInstance(bytes, seedHash);
       }
-      final boolean readOnly = (flags & READ_ONLY_FLAG_MASK) > 0;
-      if (!readOnly) {
+      default: {
         throw new SketchesArgumentException(
-            "Corrupted: COMPACT family sketch image must have Read-Only flag set");
+            "Corrupted: Serialization Version " + serVer + " not recognized.");
       }
-      return WrappedCompactSketch.wrapInstance(bytes,
-          enforceSeed ? seedHash : getShortLE(bytes, SEED_HASH_SHORT));
-    } else if (serVer == 1) {
-      return ForwardCompatibility.heapify1to3(MemorySegment.ofArray(bytes), seedHash);
-    } else if (serVer == 2) {
-      return ForwardCompatibility.heapify2to3(MemorySegment.ofArray(bytes),
-          enforceSeed ? seedHash : getShortLE(bytes, SEED_HASH_SHORT));
     }
-    throw new SketchesArgumentException(
-        "Corrupted: Serialization Version " + serVer + " not recognized.");
   }
 
   //Sketch Overrides

src/main/java/org/apache/datasketches/theta/DirectQuickSelectSketchR.java

@@ -51,8 +51,7 @@
 import org.apache.datasketches.thetacommon.ThetaUtil;
 
 /**
- * The default Theta Sketch using the QuickSelect algorithm.
- * This is the read-only implementation with non-functional methods, which affect the state.
+ * The read-only Theta Sketch using the QuickSelect algorithm.
  *
  * <p>This implementation uses data in a given MemorySegment that is owned and managed by the caller.
  * This MemorySegment can be off-heap, which if managed properly will greatly reduce the need for
@@ -65,17 +64,16 @@ class DirectQuickSelectSketchR extends UpdateSketch {
   static final double DQS_RESIZE_THRESHOLD  = 15.0 / 16.0; //tuned for space
   final long seed_; //provided, kept only on heap, never serialized.
   int hashTableThreshold_; //computed, kept only on heap, never serialized.
-  MemorySegment wseg_; //A MemorySegment for child class, but no write methods here
+  MemorySegment wseg_; //This reference is shared with the writable child class, but no write methods here
 
-  //only called by DirectQuickSelectSketch and below
+  //only called by the writable DirectQuickSelectSketch and this class.
   DirectQuickSelectSketchR(final long seed, final MemorySegment wseg) {
     seed_ = seed;
     wseg_ = wseg;
   }
 
   /**
-   * Wrap a sketch around the given source MemorySegment containing sketch data that originated from
-   * this sketch.
+   * Wrap a sketch around the given source MemorySegment containing sketch data that originated from this sketch.
    * @param srcSeg the source MemorySegment.
    * The given MemorySegment object must be in hash table form and not read only.
    * @param seed <a href="{@docRoot}/resources/dictionary.html#seed">See Update Hash Seed</a>
@@ -89,8 +87,7 @@ static DirectQuickSelectSketchR readOnlyWrap(final MemorySegment srcSeg, final l
     UpdateSketch.checkUnionQuickSelectFamily(srcSeg, preambleLongs, lgNomLongs);
     checkSegIntegrity(srcSeg, seed, preambleLongs, lgNomLongs, lgArrLongs);
 
-    final DirectQuickSelectSketchR dqssr =
-        new DirectQuickSelectSketchR(seed, srcSeg);
+    final DirectQuickSelectSketchR dqssr = new DirectQuickSelectSketchR(seed, srcSeg);
     dqssr.hashTableThreshold_ = getOffHeapHashTableThreshold(lgNomLongs, lgArrLongs);
     return dqssr;
   }

src/main/java/org/apache/datasketches/theta/Sketch.java

@@ -63,7 +63,7 @@ public abstract class Sketch implements MemorySegmentStatus {
    * was used to create the source MemorySegment image.
    *
    * <p>For Compact Sketches this method assumes that the sketch image was created with the
-   * correct hash seed, so it is not checked.</p>
+   * correct hash seed, so it is not checked. SerialVersion 1 sketches (pre-open-source) cannot be checked.</p>
    *
    * @param srcSeg an image of a Sketch.
    *
@@ -83,8 +83,12 @@ public static Sketch heapify(final MemorySegment srcSeg) {
    *
    * <p>The resulting sketch will not retain any link to the source MemorySegment.</p>
    *
-   * <p>For Update and Compact Sketches this method checks if the given expectedSeed was used to
-   * create the source MemorySegment image.  However, SerialVersion 1 sketches cannot be checked.</p>
+   * <p>For Update Sketches this method checks if the
+   * <a href="{@docRoot}/resources/dictionary.html#defaultUpdateSeed">Default Update Seed</a></p>
+   * was used to create the source MemorySegment image.
+   *
+   * <p>For Compact Sketches this method assumes that the sketch image was created with the
+   * correct hash seed, so it is not checked. SerialVersion 1 sketches (pre-open-source) cannot be checked.</p>
    *
    * @param srcSeg an image of a Sketch that was created using the given expectedSeed.
    * @param expectedSeed the seed used to validate the given MemorySegment image.
@@ -109,8 +113,7 @@ public static Sketch heapify(final MemorySegment srcSeg, final long expectedSeed
    * <p>Only "Direct" Serialization Version 3 (i.e, OpenSource) sketches that have
    * been explicitly stored as direct sketches can be wrapped.
    * Wrapping earlier serial version sketches will result in a on-heap CompactSketch
-   * where all data will be copied to the heap. These early versions were never designed to
-   * "wrap".</p>
+   * where all data will be copied to the heap. These early versions were never designed to "wrap".</p>
    *
    * <p>Wrapping any subclass of this class that is empty or contains only a single item will
    * result in on-heap equivalent forms of empty and single item sketch respectively.
@@ -121,10 +124,10 @@ public static Sketch heapify(final MemorySegment srcSeg, final long expectedSeed
    * was used to create the source MemorySegment image.
    *
    * <p>For Compact Sketches this method assumes that the sketch image was created with the
-   * correct hash seed, so it is not checked.</p>
+   * correct hash seed, so it is not checked.  SerialVersion 1 (pre-open-source) sketches cannot be checked.</p>
    *
-   * @param srcSeg an image of a Sketch.
-   * @return a Sketch backed by the given MemorySegment
+   * @param srcSeg a MemorySegment with an image of a Sketch.
+   * @return a read-only Sketch backed by the given MemorySegment
    */
   public static Sketch wrap(final MemorySegment srcSeg) {
     final int  preLongs = srcSeg.get(JAVA_BYTE, PREAMBLE_LONGS_BYTE) & 0X3F;
@@ -154,20 +157,23 @@ public static Sketch wrap(final MemorySegment srcSeg) {
    * <p>Only "Direct" Serialization Version 3 (i.e, OpenSource) sketches that have
    * been explicitly stored as direct sketches can be wrapped.
    * Wrapping earlier serial version sketches will result in a on-heap CompactSketch
-   * where all data will be copied to the heap. These early versions were never designed to
-   * "wrap".</p>
+   * where all data will be copied to the heap. These early versions were never designed to "wrap".</p>
    *
    * <p>Wrapping any subclass of this class that is empty or contains only a single item will
    * result in on-heap equivalent forms of empty and single item sketch respectively.
    * This is actually faster and consumes less overall space.</p>
    *
-   * <p>For Update and Compact Sketches this method checks if the given expectedSeed was used to
-   * create the source MemorySegment image.  However, SerialVersion 1 sketches cannot be checked.</p>
+   * <p>For Update Sketches this method checks if the
+   * <a href="{@docRoot}/resources/dictionary.html#defaultUpdateSeed">Default Update Seed</a></p>
+   * was used to create the source MemorySegment image.
+   *
+   * <p>For Compact Sketches this method assumes that the sketch image was created with the
+   * correct hash seed, so it is not checked.  SerialVersion 1 (pre-open-source) sketches cannot be checked.</p>
    *
    * @param srcSeg a MemorySegment with an image of a Sketch.
    * @param expectedSeed the seed used to validate the given MemorySegment image.
    * <a href="{@docRoot}/resources/dictionary.html#seed">See Update Hash Seed</a>.
-   * @return a UpdateSketch backed by the given MemorySegment except as above.
+   * @return a read-only Sketch backed by the given MemorySegment.
    */
   public static Sketch wrap(final MemorySegment srcSeg, final long expectedSeed) {
     final int  preLongs = srcSeg.get(JAVA_BYTE, PREAMBLE_LONGS_BYTE) & 0X3F;
@@ -203,7 +209,7 @@ public static Sketch wrap(final MemorySegment srcSeg, final long expectedSeed) {
    * @return this sketch as an ordered CompactSketch.
    */
   public CompactSketch compact() {
-    return (this.isCompact()) ? (CompactSketch)this : compact(true, null);
+    return isCompact() ? (CompactSketch)this : compact(true, null);
   }
 
   /**

src/main/java/org/apache/datasketches/theta/WrappedCompactCompressedSketch.java

@@ -28,7 +28,8 @@
 import org.apache.datasketches.common.Util;
 
 /**
- * Wrapper around a serialized compact compressed read-only sketch. It is not empty, not a single item.
+ * A wrapper around a serialized compact compressed read-only sketch in the form of a byte array.
+ * It is not an empty nor a single item sketch.
  *
  * <p>This sketch can only be associated with a Serialization Version 4 format binary image.</p>
  */

src/main/java/org/apache/datasketches/theta/WrappedCompactSketch.java

@@ -37,9 +37,10 @@
 import org.apache.datasketches.common.Util;
 
 /**
- * Wrapper around a serialized compact read-only sketch. It is not empty, not a single item.
+ * A wrapper around a serialized compact read-only sketch in the form of a byte array.
+ * It is not an empty nor a single item sketch.
  *
- * <p>This sketch can only be associated with a Serialization Version 3 format binary image.</p>
+ * <p>This sketch can only be associated with a Serialization Version 3 binary image format.</p>
  */
 class WrappedCompactSketch extends CompactSketch {
   final byte[] bytes_;