Fix Javadocs, no code changes.

datasketches-memory-java8-tests/src/test/java/org/apache/datasketches/memory/test/DruidIssue11544Test.java

@@ -48,6 +48,7 @@
  * @author Lee Rhodes
  *
  */
+@SuppressWarnings("javadoc")
 public class DruidIssue11544Test {
 
   @Test

datasketches-memory-java8-tests/src/test/java/org/apache/datasketches/memory/test/MemoryCloseExceptionTest.java

@@ -22,6 +22,7 @@
 import org.apache.datasketches.memory.MemoryCloseException;
 import org.testng.annotations.Test;
 
+@SuppressWarnings("javadoc")
 public class MemoryCloseExceptionTest {
 
   @Test

datasketches-memory-java8-tests/src/test/java/org/apache/datasketches/memory/test/ReflectUtil.java

@@ -28,6 +28,7 @@
 
 import org.apache.datasketches.memory.MemoryRequestServer;
 
+@SuppressWarnings("javadoc")
 public final class ReflectUtil {
 
   private ReflectUtil() {}

datasketches-memory-java8-tests/src/test/java/org/apache/datasketches/memory/test/UnsafeUtilTest.java

@@ -34,6 +34,7 @@
 /**
  * @author Lee Rhodes
  */
+@SuppressWarnings("javadoc")
 public class UnsafeUtilTest {
   long testField = 1; //Do not remove & cannot be static. Used in reflection check.
 

datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/BaseBuffer.java

@@ -19,6 +19,11 @@
 
 package org.apache.datasketches.memory;
 
+/**
+ * Defines the relative positional API.
+ *
+ * @author Lee Rhodes
+ */
 public interface BaseBuffer extends BaseState {
 
   /**
@@ -116,11 +121,4 @@ public interface BaseBuffer extends BaseState {
    */
   BaseBuffer setAndCheckStartPositionEnd(long start, long position, long end);
 
-
-
-
-
-
-
-
 }

datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/BaseState.java

@@ -32,7 +32,10 @@
  * @author Lee Rhodes
  */
 public interface BaseState {
-  static final MemoryRequestServer defaultMemReqSvr = null;//new DefaultMemoryRequestServer(); //or null.
+  /**
+   * The placeholder for the default MemoryRequestServer, if set at all.
+   */
+  static final MemoryRequestServer defaultMemReqSvr = null; //new DefaultMemoryRequestServer();
 
   //Byte Order Related
 

datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Buffer.java

@@ -27,6 +27,11 @@
 
 import org.apache.datasketches.memory.internal.BaseWritableBufferImpl;
 
+/**
+ * Defines the read-only API for relative positional access to a resource.
+ *
+ * @author Lee Rhodes
+ */
 public interface Buffer extends BaseBuffer {
 
   //BYTE BUFFER
@@ -144,6 +149,7 @@ default Memory asMemory() {
   /**
    * Convert this Buffer to a Memory with the given byte order.
    * The current <i>start</i>, <i>position</i> and <i>end</i> are ignored.
+   * @param byteOrder the given byte order.
    * @return Memory
    */
   Memory asMemory(ByteOrder byteOrder);

datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Memory.java

@@ -33,14 +33,19 @@
 import org.apache.datasketches.memory.internal.Prim;
 import org.apache.datasketches.memory.internal.UnsafeUtil;
 
+/**
+ * Defines the read-only API for offset access to a resource.
+ *
+ * @author Lee Rhodes
+ */
 public interface Memory extends BaseState {
 
   //BYTE BUFFER
 
   /**
    * Accesses the given <i>ByteBuffer</i> for read-only operations. The returned <i>Memory</i> object has
    * the same byte order, as the given <i>ByteBuffer</i>.
-   * @param byteBuffer the given <i>ByteBuffer</i>. It must be non-null and with capacity >= 0.
+   * @param byteBuffer the given <i>ByteBuffer</i>. It must be non-null and with capacity &ge; 0.
    * @return a new <i>Memory</i> for read-only operations on the given <i>ByteBuffer</i>.
    */
   static Memory wrap(ByteBuffer byteBuffer) {
@@ -50,7 +55,7 @@ static Memory wrap(ByteBuffer byteBuffer) {
   /**
    * Accesses the given <i>ByteBuffer</i> for read-only operations. The returned <i>Memory</i> object has
    * the given byte order, ignoring the byte order of the given <i>ByteBuffer</i> for future reads and writes.
-   * @param byteBuffer the given <i>ByteBuffer</i>. It must be non-null and with capacity >= 0.
+   * @param byteBuffer the given <i>ByteBuffer</i>. It must be non-null and with capacity &ge; 0.
    * @param byteOrder the byte order to be used.  It must be non-null.
    * @return a new <i>Memory</i> for read-only operations on the given <i>ByteBuffer</i>.
    */
@@ -66,7 +71,7 @@ static Memory wrap(ByteBuffer byteBuffer, ByteOrder byteOrder) {
    * Maps the entire given file into native-ordered <i>Memory</i> for read operations
    * Calling this method is equivalent to calling
    * {@link #map(File, long, long, ByteOrder) map(file, 0, file.length(), ByteOrder.nativeOrder())}.
-   * @param file the given file to map. It must be non-null, length >= 0, and readable.
+   * @param file the given file to map. It must be non-null, length &ge; 0, and readable.
    * @return <i>MapHandle</i> for managing the mapped memory.
    * Please read Javadocs for {@link Handle}.
    */
@@ -99,8 +104,8 @@ static MapHandle map(File file, long fileOffsetBytes, long capacityBytes, ByteOr
    * <li>Returned object's origin = this object's origin + offsetBytes</li>
    * <li>Returned object's capacity = capacityBytes</li>
    * </ul>
-   * @param offsetBytes the starting offset with respect to the origin of this <i>Memory</i>. It must be >=0.
-   * @param capacityBytes the capacity of the region in bytes. It must be >= 0.
+   * @param offsetBytes the starting offset with respect to the origin of this <i>Memory</i>. It must be &ge; 0.
+   * @param capacityBytes the capacity of the region in bytes. It must be &ge; 0.
    * @return a new <i>Memory</i> representing the defined region based on the given
    * offsetBytes and capacityBytes.
    */
@@ -115,8 +120,8 @@ default Memory region(long offsetBytes, long capacityBytes) {
    * <li>Returned object's capacity = <i>capacityBytes</i></li>
    * <li>Returned object's byte order = <i>byteOrder</i></li>
    * </ul>
-   * @param offsetBytes the starting offset with respect to the origin of this Memory. It must be >=0.
-   * @param capacityBytes the capacity of the region in bytes. It must be >= 0.
+   * @param offsetBytes the starting offset with respect to the origin of this Memory. It must be &ge; 0.
+   * @param capacityBytes the capacity of the region in bytes. It must be &ge; 0.
    * @param byteOrder the given byte order. It must be non-null.
    * @return a new <i>Memory</i> representing the defined region based on the given
    * offsetBytes, capacityBytes and byteOrder.

datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MemoryCloseException.java

@@ -28,10 +28,18 @@
 public class MemoryCloseException extends MemoryException {
   private static final long serialVersionUID = 2L;
 
+  /**
+   * The associated resource failed to close.
+   */
   public MemoryCloseException() {
     super("The associated resource failed to close.");
   }
 
+  /**
+   * The associated resource failed to close, with comment
+   *
+   * @param resource the named resource that failed to close, plus other comments.
+   */
   public MemoryCloseException(final String resource) {
     super("The associated resource, " + resource + ", failed to close");
   }

datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/MemoryRequestServer.java

@@ -31,7 +31,7 @@ public interface MemoryRequestServer {
    * Request new WritableMemory with the given capacity. The current Writable Memory will be used to
    * determine the byte order of the returned WritableMemory and other checks.
    * @param currentWritableMemory the current writableMemory of the client. It must be non-null.
-   * @param capacityBytes The capacity being requested. It must be >0.
+   * @param capacityBytes The capacity being requested. It must be ≥ 0.
    *
    * @return new WritableMemory with the given capacity.
    */

datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/Utf8CodingException.java

@@ -37,36 +37,69 @@ public Utf8CodingException(final String message) {
     super(message);
   }
 
-  //Decode
+  //DECODE
+  /**
+   * Exception for a short UTF_8 Decode Byte Sequence
+   * @param leadByte the given lead byte
+   * @param address the given address
+   * @param limit the given limit
+   * @param required what is required
+   * @return the exception
+   */
   public static Utf8CodingException shortUtf8DecodeByteSequence(final byte leadByte, final long address,
       final long limit, final int required) {
     final String s = "Too few Utf8 decode bytes remaining given the leading byte. "
         + shortSeq(leadByte, address, limit, required);
     return new Utf8CodingException(s);
   }
 
+  /**
+   * Exception for an illegal UTF_8 Decode Byte Sequence
+   * @param bytes the illegal byte sequence
+   * @return the exception.
+   */
   public static Utf8CodingException illegalUtf8DecodeByteSequence(final byte[] bytes) {
     final String s = "Invalid UTF-8 decode byte sequence: " + badBytes(bytes);
     return new Utf8CodingException(s);
   }
 
-  //Encode
+  //ENCODE
+  /**
+   * Exception for out-of-memory
+   * @return the exception
+   */
   public static Utf8CodingException outOfMemory() {
     final String s = "Out-of-memory with characters remaining to be encoded";
     return new Utf8CodingException(s);
   }
 
+  /**
+   * Exception for an unpaired surrogate
+   * @param c The last char to encode is an unpaired surrogate
+   * @return the exception plus the unpaired surrogate character
+   */
   public static Utf8CodingException unpairedSurrogate(final char c) {
     final String s = "Last char to encode is an unpaired surrogate: 0X"
         + Integer.toHexString(c & 0XFFFF);
     return new Utf8CodingException(s);
   }
 
+  /**
+   * Exception for a short UTF_8 encode byte length
+   * @param remaining The surrogate pair that is short
+   * @return the exception plus the surrogate pair that is short
+   */
   public static Utf8CodingException shortUtf8EncodeByteLength(final int remaining) {
     final String s = "Too few MemoryImpl bytes to encode a surrogate pair: " + remaining;
     return new Utf8CodingException(s);
   }
 
+  /**
+   * Exception for an illegal surrogate pair
+   * @param c1 the first character of the pair
+   * @param c2 the second character of the pair
+   * @return the exception plus the illegal pair
+   */
   public static Utf8CodingException illegalSurrogatePair(final char c1, final char c2) {
     final String s = "Illegal Surrogate Pair: Char 1: " + Integer.toHexString(c1 & 0XFFFF)
       + ", Char 2: " + Integer.toHexString(c2 & 0XFFFF);

datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/WritableBuffer.java

@@ -27,6 +27,11 @@
 import org.apache.datasketches.memory.internal.BaseWritableBufferImpl;
 import org.apache.datasketches.memory.internal.Util;
 
+/**
+ * Defines the writable API for relative positional access to a resource
+ *
+ * @author Lee Rhodes
+ */
 public interface WritableBuffer extends Buffer {
 
   //BYTE BUFFER
@@ -154,6 +159,7 @@ default WritableMemory asWritableMemory() {
    * Convert this WritableBuffer to a WritableMemory with the given byte order.
    * If this object's capacity is zero, the returned object is effectively immutable and
    * the backing storage and byte order are unspecified.
+   * @param byteOrder the byte order to be used.
    * @return WritableMemory
    */
   WritableMemory asWritableMemory(ByteOrder byteOrder);

datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/WritableMemory.java

@@ -17,7 +17,6 @@
  * under the License.
  */
 
-
 package org.apache.datasketches.memory;
 
 import static org.apache.datasketches.memory.internal.Util.negativeCheck;
@@ -31,6 +30,11 @@
 import org.apache.datasketches.memory.internal.Prim;
 import org.apache.datasketches.memory.internal.UnsafeUtil;
 
+/**
+ * Defines the writable API for offset access to a resource.
+ *
+ * @author Lee Rhodes
+ */
 public interface WritableMemory extends Memory {
 
   //BYTE BUFFER

datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/XxHash.java

@@ -49,7 +49,7 @@
  */
 public final class XxHash {
 
-  public XxHash() { /* singleton */ }
+  private XxHash() { /* singleton */ }
 
   /**
    * Hash the given arr starting at the given offset and continuing for the given length using the

datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/BaseStateImpl.java

@@ -340,7 +340,11 @@ final boolean isBBType() {
 
 
   //TO STRING
-  //For debugging
+  /**
+   * Decodes the resource type. This is primarily for debugging.
+   * @param typeId the given typeId
+   * @return a human readable string.
+   */
   public static final String typeDecode(final int typeId) {
     StringBuilder sb = new StringBuilder();
     int group1 = typeId & 0x7;

datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/BaseWritableBufferImpl.java

@@ -67,6 +67,14 @@ public abstract class BaseWritableBufferImpl extends BaseBufferImpl implements W
     super(unsafeObj, nativeBaseOffset, regionOffset, capacityBytes);
   }
 
+  /**
+   * The static constructor that chooses the correct ByteBuffer leaf node based on the byte order.
+   * @param byteBuf the ByteBuffer being wrapped
+   * @param localReadOnly the requested read-only state
+   * @param byteOrder the requested byteOrder
+   * @param memReqSvr the requested MemoryRequestServer, which may be null.
+   * @return this class constructed via the leaf node.
+   */
   public static BaseWritableBufferImpl wrapByteBuffer(
       final ByteBuffer byteBuf, final boolean localReadOnly, final ByteOrder byteOrder,
       final MemoryRequestServer memReqSvr) {

datasketches-memory-java8/src/main/java/org/apache/datasketches/memory/internal/BaseWritableMemoryImpl.java

@@ -80,15 +80,32 @@ public abstract class BaseWritableMemoryImpl extends BaseStateImpl implements Wr
     super(unsafeObj, nativeBaseOffset, regionOffset, capacityBytes);
   }
 
+  /**
+   * The static constructor that chooses the correct Heap leaf node based on the byte order.
+   * @param arr the primitive heap array being wrapped
+   * @param offsetBytes the offset bytes into the array (independent of array type).
+   * @param lengthBytes the length of the wrapped region.
+   * @param localReadOnly the requested read-only status
+   * @param byteOrder the requested byte order
+   * @param memReqSvr the requested MemoryRequestServer, which may be null.
+   * @return this class constructed via the leaf node.
+   */
   public static BaseWritableMemoryImpl wrapHeapArray(final Object arr, final long offsetBytes, final long lengthBytes,
       final boolean localReadOnly, final ByteOrder byteOrder, final MemoryRequestServer memReqSvr) {
-
     final int typeId = localReadOnly ? READONLY : 0;
     return Util.isNativeByteOrder(byteOrder)
         ? new HeapWritableMemoryImpl(arr, offsetBytes, lengthBytes, typeId, memReqSvr)
         : new HeapNonNativeWritableMemoryImpl(arr, offsetBytes, lengthBytes, typeId, memReqSvr);
   }
 
+  /**
+   * The static constructor that chooses the correct ByteBuffer leaf node based on the byte order.
+   * @param byteBuf the ByteBuffer being wrapped
+   * @param localReadOnly the requested read-only state
+   * @param byteOrder the requested byteOrder
+   * @param memReqSvr the requested MemoryRequestServer, which may be null.
+   * @return this class constructed via the leaf node.
+   */
   public static BaseWritableMemoryImpl wrapByteBuffer(
       final ByteBuffer byteBuf, final boolean localReadOnly, final ByteOrder byteOrder,
       final MemoryRequestServer memReqSvr) {
@@ -101,6 +118,15 @@ public static BaseWritableMemoryImpl wrapByteBuffer(
             abb.regionOffset, abb.capacityBytes,  typeId, byteBuf, memReqSvr);
   }
 
+  /**
+   * The static constructor that chooses the correct Map leaf node based on the byte order.
+   * @param file the file being wrapped.
+   * @param fileOffsetBytes the file offset bytes
+   * @param capacityBytes the requested capacity of the memory mapped region
+   * @param localReadOnly the requested read-only state
+   * @param byteOrder the requested byte-order
+   * @return this class constructed via the leaf node.
+   */
   @SuppressWarnings("resource")
   public static WritableMapHandle wrapMap(final File file, final long fileOffsetBytes,
       final long capacityBytes, final boolean localReadOnly, final ByteOrder byteOrder) {
@@ -115,6 +141,13 @@ public static WritableMapHandle wrapMap(final File file, final long fileOffsetBy
     return new WritableMapHandleImpl(dirWMap, wmem);
   }
 
+  /**
+   * The static constructor that chooses the correct Direct leaf node based on the byte order.
+   * @param capacityBytes the requested capacity for the Direct (off-heap) memory
+   * @param byteOrder the requested byte order
+   * @param memReqSvr the requested MemoryRequestServer, which may be null
+   * @return this class constructed via the leaf node.
+   */
   @SuppressWarnings("resource")
   public static WritableHandle wrapDirect(final long capacityBytes,
       final ByteOrder byteOrder, final MemoryRequestServer memReqSvr) {