Improved javadocs

Author: leerho

src/main/java/org/apache/datasketches/kll/KllDirectCompactItemsSketch.java

@@ -63,7 +63,7 @@ final class KllDirectCompactItemsSketch<T> extends KllItemsSketch<T> {
       final Comparator<? super T> comparator,
       final ArrayOfItemsSerDe<T> serDe) {
     super(segVal.sketchStructure, comparator, serDe);
-    seg = segVal.srcSeg;
+    seg = segVal.srcSeg.asReadOnly();
     readOnly = true;
     levelsArr = segVal.levelsArr; //always converted to writable form.
   }

src/main/java/org/apache/datasketches/kll/KllDoublesSketch.java

@@ -132,17 +132,14 @@ public static KllDoublesSketch heapify(final MemorySegment srcSeg) {
   /**
    * Wrap a sketch around the given source MemorySegment containing sketch data that originated from this sketch.
    *
-   * <p>If the given MemorySegment is writable and if the {@link KllSketch.SketchStructure SketchStructure} of the MemorySegment is
-   * {@link #UPDATABLE UPDATABLE}, 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.<br></p>
+   * <p>The given MemorySegment must be writable and it must contain a <i>KllDoublesSketch</i> in updatable form.
+   * 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>
    *
-   * <p>If the given MemorySegment is read-only or if the SketchStructure is not UPDATABLE, than the sketch can be read but not written to
-   * independent of whether the MemorySegment was created on-heap or off-heap.</p>
-   *
    * @param srcSeg a MemorySegment that contains sketch data.
    * @return an instance of this sketch that wraps the given MemorySegment.
    */
@@ -153,23 +150,21 @@ public static KllDoublesSketch wrap(final MemorySegment srcSeg) {
   }
 
   /**
-   * Wrap a sketch around the given source MemorySegment containing sketch data that originated from this sketch and including a user
-   * defined {@link MemorySegmentRequest MemorySegmentRequest}.
+   * 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>If the given MemorySegment is writable and if the {@link KllSketch.SketchStructure SketchStructure} of the MemorySegment is
-   * {@link #UPDATABLE UPDATABLE}, 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.<br></p>
+   * <p>The given MemorySegment must be writable and it must contain a <i>KllDoublesSketch</i> in updatable form.
+   * 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>
    *
-   * <p>If the given MemorySegment is read-only or if the SketchStructure is not UPDATABLE, than the sketch can be read,
-   * but not written to, independent of whether the MemorySegment was created on-heap or off-heap.</p>
-   *
    * @param srcSeg a MemorySegment that contains sketch data.
-   * @param mSegReq the callback for the sketch to request a larger MemorySegment. It may be null.
+   * @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 an instance of this sketch that wraps the given MemorySegment.
    */
   public static KllDoublesSketch wrap(final MemorySegment srcSeg, final MemorySegmentRequest mSegReq) {

src/main/java/org/apache/datasketches/kll/KllFloatsSketch.java

@@ -132,17 +132,14 @@ public static KllFloatsSketch heapify(final MemorySegment srcSeg) {
   /**
    * Wrap a sketch around the given source MemorySegment containing sketch data that originated from this sketch.
    *
-   * <p>If the given MemorySegment is writable and if the {@link KllSketch.SketchStructure SketchStructure} of the MemorySegment is
-   * {@link #UPDATABLE UPDATABLE}, 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.<br></p>
+   * <p>The given MemorySegment must be writable and it must contain a <i>KllFloatsSketch</i> in updatable form.
+   * 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>
    *
-   * <p>If the given MemorySegment is read-only or if the SketchStructure is not UPDATABLE, than the sketch can be read but not written to
-   * independent of whether the MemorySegment was created on-heap or off-heap.</p>
-   *
    * @param srcSeg a MemorySegment that contains sketch data.
    * @return an instance of this sketch that wraps the given MemorySegment.
    */
@@ -153,26 +150,24 @@ public static KllFloatsSketch wrap(final MemorySegment srcSeg) {
   }
 
   /**
-   * Wrap a sketch around the given source MemorySegment containing sketch data that originated from this sketch and including a user
-   * defined {@link MemorySegmentRequest MemorySegmentRequest}.
+   * 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>If the given MemorySegment is writable and if the {@link KllSketch.SketchStructure SketchStructure} of the MemorySegment is
-   * {@link #UPDATABLE UPDATABLE}, 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.<br></p>
+   * <p>The given MemorySegment must be writable and it must contain a <i>KllFloatsSketch</i> in updatable form.
+   * 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>
    *
-   * <p>If the given MemorySegment is read-only or if the SketchStructure is not UPDATABLE, than the sketch can be read,
-   * but not written to, independent of whether the MemorySegment was created on-heap or off-heap.</p>
-   *
    * @param srcSeg a MemorySegment that contains sketch data.
-   * @param mSegReq the callback for the sketch to request a larger MemorySegment. It may be null.
+   * @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 an instance of this sketch that wraps the given MemorySegment.
    */
-  public static KllFloatsSketch writableWrap(final MemorySegment srcSeg, final MemorySegmentRequest mSegReq) {
+  public static KllFloatsSketch wrap(final MemorySegment srcSeg, final MemorySegmentRequest mSegReq) {
     Objects.requireNonNull(srcSeg, "Parameter 'srcSeg' must not be null");
     final KllMemorySegmentValidate segVal = new KllMemorySegmentValidate(srcSeg, FLOATS_SKETCH);
     return new KllDirectFloatsSketch(srcSeg, segVal, mSegReq);

src/main/java/org/apache/datasketches/kll/KllItemsSketch.java

@@ -124,8 +124,8 @@ public static <T> KllItemsSketch<T> heapify(
    * A reference to the MemorySegment is kept in the sketch and must remain in scope consistent
    * with the temporal scope of this sketch. The amount of data kept on the heap is very small.
    * All of the item data originally collected by the given MemorySegment sketch object remains in the
-   * MemorySegment object
-   * @param srcSeg the MemorySegment object that this sketch will wrap.
+   * MemorySegment object.
+   * @param srcSeg the MemorySegment object that this sketch will wrap. It will not be modified.
    * @param comparator to compare items
    * @param serDe Serializer / deserializer for items of type <i>T</i> and <i>T[]</i>.
    * @param <T> The sketch data type

src/main/java/org/apache/datasketches/kll/KllLongsSketch.java

@@ -132,17 +132,14 @@ public static KllLongsSketch heapify(final MemorySegment srcSeg) {
   /**
    * Wrap a sketch around the given source MemorySegment containing sketch data that originated from this sketch.
    *
-   * <p>If the given MemorySegment is writable and if the {@link KllSketch.SketchStructure SketchStructure} of the MemorySegment is
-   * {@link #UPDATABLE UPDATABLE}, 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.<br></p>
+   * <p>The given MemorySegment must be writable and it must contain a <i>KllLongsSketch</i> in updatable form.
+   * 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>
    *
-   * <p>If the given MemorySegment is read-only or if the SketchStructure is not UPDATABLE, than the sketch can be read but not written to
-   * independent of whether the MemorySegment was created on-heap or off-heap.</p>
-   *
    * @param srcSeg a MemorySegment that contains sketch data.
    * @return an instance of this sketch that wraps the given MemorySegment.
    */
@@ -153,23 +150,21 @@ public static KllLongsSketch wrap(final MemorySegment srcSeg) {
   }
 
   /**
-   * Wrap a sketch around the given source MemorySegment containing sketch data that originated from this sketch and including a user
-   * defined {@link MemorySegmentRequest MemorySegmentRequest}.
+   * 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>If the given MemorySegment is writable and if the {@link KllSketch.SketchStructure SketchStructure} of the MemorySegment is
-   * {@link #UPDATABLE UPDATABLE}, 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.<br></p>
+   * <p>The given MemorySegment must be writable and it must contain a <i>KllLongsSketch</i> in updatable form.
+   * 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>
    *
-   * <p>If the given MemorySegment is read-only or if the SketchStructure is not UPDATABLE, than the sketch can be read,
-   * but not written to, independent of whether the MemorySegment was created on-heap or off-heap.</p>
-   *
    * @param srcSeg a MemorySegment that contains sketch data.
-   * @param mSegReq the callback for the sketch to request a larger MemorySegment. It may be null.
+   * @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 an instance of this sketch that wraps the given MemorySegment.
    */
   public static KllLongsSketch wrap(final MemorySegment srcSeg, final MemorySegmentRequest mSegReq) {