Correcting javadocs

Author: leerho

src/main/java/org/apache/datasketches/quantiles/DirectCompactDoublesSketch.java

@@ -250,7 +250,7 @@ static void checkDirectSegCapacity(final int k, final long n, final long segCapB
   /**
    * Checks a sketch's serial version and flags to see if the sketch can be wrapped as a
    * DirectCompactDoubleSketch. Throws an exception if the sketch is neither empty nor compact
-   * and ordered, unles the sketch uses serialization version 2.
+   * and ordered, unless the sketch uses serialization version 2.
    * @param serVer the serialization version
    * @param flags Flags from the sketch to evaluate
    */

src/main/java/org/apache/datasketches/quantiles/DirectUpdateDoublesSketch.java

@@ -384,7 +384,7 @@ static void checkDirectSegCapacity(final int k, final long n, final long segCapB
   static void checkCompact(final int serVer, final int flags) {
     final boolean compact = (serVer == 2) || ((flags & COMPACT_FLAG_MASK) > 0);
     if (compact) {
-      throw new SketchesArgumentException("Compact MemorySegment is not supported for Wrap Instance.");
+      throw new SketchesArgumentException("MemorySegment is in compact form and is not supported for this writableWrap Instance.");
     }
   }
 

src/main/java/org/apache/datasketches/quantiles/DoublesSketch.java

@@ -151,29 +151,59 @@ public static DoublesSketch heapify(final MemorySegment srcSeg) {
   }
 
   /**
-   * Wrap this sketch around the given updatable MemorySegment image of a DoublesSketch, compact or updatable.
+   * Wrap this sketch around the given MemorySegment image of a compact, read-only DoublesSketch.
    *
-   * @param srcSeg the given MemorySegment image of a DoublesSketch that may have data
-   * @return a sketch that wraps the given srcSeg in read-only mode.
+   * @param srcSeg the given MemorySegment image of a compact, read-only DoublesSketch.
+   * @return a compact, read-only sketch that wraps the given MemorySegment.
    */
   public static DoublesSketch wrap(final MemorySegment srcSeg) {
+    if (!checkIsMemorySegmentCompact(srcSeg)) {
+      throw new SketchesArgumentException("MemorySegment sketch image must be in compact form.");
+    }
+    return DirectCompactDoublesSketch.wrapInstance(srcSeg);
+  }
+
+  /**
+   * Wrap this sketch around the given MemorySegment image of an updatable DoublesSketch.
+   *
+   * <p>The given MemorySegment must be writable and it must contain a <i>UpdateDoublesSketch</i>.
+   * The sketch will be updated and managed totally within the MemorySegment. If the given source
+   * MemorySegment is created off-heap, then all the management of the sketch's internal data will be off-heap as well.</p>
+   *
+   * <p><b>NOTE:</b>If during updating of the sketch the sketch requires more capacity than the given size of the MemorySegment, the sketch
+   * will request more capacity using the {@link MemorySegmentRequest MemorySegmentRequest} interface. The default of this interface will
+   * return a new MemorySegment on the heap.</p>
+   *
+   * @param srcSeg the given MemorySegment image of an <i>UpdateDoublesSketch</i>.
+   * @return an updatable sketch that wraps the given MemorySegment.
+   */
+  public static DoublesSketch writableWrap(final MemorySegment srcSeg) {
     if (checkIsMemorySegmentCompact(srcSeg)) {
-      return DirectCompactDoublesSketch.wrapInstance(srcSeg);
+      throw new SketchesArgumentException("MemorySegment sketch image must be in updatable form.");
     }
     return DirectUpdateDoublesSketch.wrapInstance(srcSeg, null);
   }
 
   /**
-   * Wrap this sketch around the given updatable MemorySegment image of a DoublesSketch, compact or updatable.
+   * Wrap this sketch around the given MemorySegment image of an updatable DoublesSketch.
+   *
+   * <p>The given MemorySegment must be writable and it must contain a <i>UpdateDoublesSketch</i>.
+   * The sketch will be updated and managed totally within the MemorySegment. If the given source
+   * MemorySegment is created off-heap, then all the management of the sketch's internal data will be off-heap as well.</p>
+   *
+   * <p><b>NOTE:</b>If during updating of the sketch the sketch requires more capacity than the given size of the MemorySegment, the sketch
+   * will request more capacity using the {@link MemorySegmentRequest MemorySegmentRequest} interface. The default of this interface will
+   * return a new MemorySegment on the heap. It is up to the user to optionally extend this interface if more flexible
+   * handling of requests for more capacity is required.</p>
    *
-   * @param srcSeg the given MemorySegment image of a DoublesSketch that may have data.
+   * @param srcSeg the given MemorySegment image of a DoublesSketch.
    * @param mSegReq the MemorySegmentRequest used if the given MemorySegment needs to expand.
    * Otherwise, it can be null and the default MemorySegmentRequest will be used.
-   * @return a sketch that wraps the given srcSeg in read-only mode.
+   * @return a sketch that wraps the given MemorySegment.
    */
-  public static DoublesSketch wrap(final MemorySegment srcSeg, final MemorySegmentRequest mSegReq) {
+  public static DoublesSketch writableWrap(final MemorySegment srcSeg, final MemorySegmentRequest mSegReq) {
     if (checkIsMemorySegmentCompact(srcSeg)) {
-      return DirectCompactDoublesSketch.wrapInstance(srcSeg);
+      throw new SketchesArgumentException("MemorySegment sketch image must be in updatable form.");
     }
     return DirectUpdateDoublesSketch.wrapInstance(srcSeg, mSegReq);
   }

src/main/java/org/apache/datasketches/quantiles/DoublesUnionImpl.java

@@ -138,7 +138,7 @@ public void union(final DoublesSketch sketchIn) {
   @Override
   public void union(final MemorySegment seg) {
     Objects.requireNonNull(seg);
-    gadget_ = updateLogic(maxK_, gadget_, DoublesSketch.wrap(seg, null));
+    gadget_ = updateLogic(maxK_, gadget_, DoublesSketch.writableWrap(seg, null));
     gadget_.doublesSV = null;
   }
 

src/main/java/org/apache/datasketches/quantiles/UpdateDoublesSketch.java

@@ -34,22 +34,40 @@ public abstract class UpdateDoublesSketch extends DoublesSketch {
   }
 
   /**
-   * Wrap this sketch around the given MemorySegment image of an UpdateDoublesSketch.
+   * Wrap a sketch around the given source MemorySegment containing sketch data that originated from this sketch.
    *
-   * @param srcSeg the given MemorySegment image of an UpdateDoublesSketch and must not be null.
-   * @return a sketch that wraps the given srcSeg
+   * <p>The given MemorySegment must be writable and it must contain a <i>UpdateDoublesSketch</i>.
+   * The sketch will be updated and managed totally within the MemorySegment. If the given source
+   * MemorySegment is created off-heap, then all the management of the sketch's internal data will be off-heap as well.</p>
+   *
+   * <p><b>NOTE:</b>If during updating of the sketch the sketch requires more capacity than the given size of the MemorySegment, the sketch
+   * will request more capacity using the {@link MemorySegmentRequest MemorySegmentRequest} interface. The default of this interface will
+   * return a new MemorySegment on the heap.</p>
+   *
+   * @param srcSeg a MemorySegment that contains sketch data.
+   * @return an instance of this sketch that wraps the given MemorySegment.
    */
   public static UpdateDoublesSketch wrap(final MemorySegment srcSeg) {
     return DirectUpdateDoublesSketch.wrapInstance(srcSeg, null);
   }
 
   /**
-   * Wrap this sketch around the given MemorySegment image of an UpdateDoublesSketch.
+   * Wrap a sketch around the given source MemorySegment containing sketch data that originated from this sketch and including an
+   * optional, user defined {@link MemorySegmentRequest MemorySegmentRequest}.
+   *
+   * <p>The given MemorySegment must be writable and it must contain a <i>UpdateDoublesSketch</i>.
+   * The sketch will be updated and managed totally within the MemorySegment. If the given source
+   * MemorySegment is created off-heap, then all the management of the sketch's internal data will be off-heap as well.</p>
+   *
+   * <p><b>NOTE:</b>If during updating of the sketch the sketch requires more capacity than the given size of the MemorySegment, the sketch
+   * will request more capacity using the {@link MemorySegmentRequest MemorySegmentRequest} interface. The default of this interface will
+   * return a new MemorySegment on the heap. It is up to the user to optionally extend this interface if more flexible
+   * handling of requests for more capacity is required.</p>
    *
-   * @param srcSeg the given MemorySegment image of an UpdateDoublesSketch and must not be null.
+   * @param srcSeg a MemorySegment that contains sketch data.
    * @param mSegReq the MemorySegmentRequest used if the given MemorySegment needs to expand.
    * Otherwise, it can be null and the default MemorySegmentRequest will be used.
-   * @return a sketch that wraps the given srcSeg
+   * @return an instance of this sketch that wraps the given MemorySegment.
    */
   public static UpdateDoublesSketch wrap(final MemorySegment srcSeg, final MemorySegmentRequest mSegReq) {
     return DirectUpdateDoublesSketch.wrapInstance(srcSeg, mSegReq);