Merge pull request #553 from apache/improve_javadocs
Improved javadocs for main code.
diff --git a/src/main/java/org/apache/datasketches/cpc/CompressionCharacterization.java b/src/main/java/org/apache/datasketches/cpc/CompressionCharacterization.java
index 962b288..4f0a933 100644
--- a/src/main/java/org/apache/datasketches/cpc/CompressionCharacterization.java
+++ b/src/main/java/org/apache/datasketches/cpc/CompressionCharacterization.java
@@ -68,6 +68,18 @@
private CompressedState[] compressedStates2;
private CpcSketch[] unCompressedSketches;
+ /**
+ * Only used in test.
+ * @param lgMinK min lgK
+ * @param lgMaxK max lgK
+ * @param lgMinT min lgTrials
+ * @param lgMaxT max lgTrials
+ * @param lgMulK lg multiple
+ * @param uPPO unique axis Points Per Octave
+ * @param incLgK increment lgK
+ * @param pS PrintStream
+ * @param pW PrintWriter
+ */
@SuppressFBWarnings(value = "EI_EXPOSE_REP2", justification = "This is OK here")
public CompressionCharacterization(
final int lgMinK,
@@ -91,6 +103,9 @@
assembleFormats();
}
+ /**
+ * Only used in test
+ */
public void start() {
printf(hfmt, (Object[]) hStrArr); //print header
doRangeOfLgK();
diff --git a/src/main/java/org/apache/datasketches/filters/bloomfilter/BloomFilter.java b/src/main/java/org/apache/datasketches/filters/bloomfilter/BloomFilter.java
index 0c957ce..3ea73b9 100644
--- a/src/main/java/org/apache/datasketches/filters/bloomfilter/BloomFilter.java
+++ b/src/main/java/org/apache/datasketches/filters/bloomfilter/BloomFilter.java
@@ -54,10 +54,12 @@
* false positive probability.</p>
*
* <p>This implementation uses xxHash64 and follows the approach in Kirsch and Mitzenmacher,
- * "Less Hashing, Same Performance: Building a Better Bloom Filter," Wiley Interscience, 2008,
- * pp. 187-218.</p>
+ * "Less Hashing, Same Performance: Building a Better Bloom Filter," Wiley Interscience, 2008, pp. 187-218.</p>
*/
public final class BloomFilter {
+ /**
+ * The maximum size of a bloom filter in bits.
+ */
public static final long MAX_SIZE_BITS = (Integer.MAX_VALUE - Family.BLOOMFILTER.getMaxPreLongs()) * (long) Long.SIZE;
private static final int SER_VER = 1;
private static final int EMPTY_FLAG_MASK = 4;
@@ -133,11 +135,23 @@
return internalHeapifyOrWrap((WritableMemory) mem, false, false);
}
+ /**
+ * Wraps the given Memory into this filter class. The class itself only contains a few metadata items and holds
+ * a reference to the Memory object, which contains all the data.
+ * @param mem the given Memory object
+ * @return the wrapping BloomFilter class.
+ */
public static BloomFilter wrap(final Memory mem) {
// casting to writable, but tracking that the object is read-only
return internalHeapifyOrWrap((WritableMemory) mem, true, false);
}
+ /**
+ * Wraps the given WritableMemory into this filter class. The class itself only contains a few metadata items and holds
+ * a reference to the Memory object, which contains all the data.
+ * @param wmem the given WritableMemory object
+ * @return the wrapping BloomFilter class.
+ */
public static BloomFilter writableWrap(final WritableMemory wmem) {
return internalHeapifyOrWrap(wmem, true, true);
}
diff --git a/src/main/java/org/apache/datasketches/filters/bloomfilter/DirectBitArrayR.java b/src/main/java/org/apache/datasketches/filters/bloomfilter/DirectBitArrayR.java
index 19c495a..8acc36b 100644
--- a/src/main/java/org/apache/datasketches/filters/bloomfilter/DirectBitArrayR.java
+++ b/src/main/java/org/apache/datasketches/filters/bloomfilter/DirectBitArrayR.java
@@ -24,6 +24,9 @@
import org.apache.datasketches.memory.Memory;
import org.apache.datasketches.memory.WritableMemory;
+/**
+ * This class can maintain the BitArray object off-heap.
+ */
public class DirectBitArrayR extends BitArray {
final static protected long NUM_BITS_OFFSET = Long.BYTES;
final static protected long DATA_OFFSET = 2L * Long.BYTES;
diff --git a/src/main/java/org/apache/datasketches/hll/TgtHllType.java b/src/main/java/org/apache/datasketches/hll/TgtHllType.java
index a0ee79a..a5dc395 100644
--- a/src/main/java/org/apache/datasketches/hll/TgtHllType.java
+++ b/src/main/java/org/apache/datasketches/hll/TgtHllType.java
@@ -50,10 +50,27 @@
* </ul>
* @author Lee Rhodes
*/
-public enum TgtHllType { HLL_4, HLL_6, HLL_8;
+public enum TgtHllType {
+ /**
+ * An HLL sketch with a bin size of 4 bits
+ */
+ HLL_4,
+ /**
+ * An HLL sketch with a bin size of 6 bits
+ */
+ HLL_6,
+ /**
+ * An Hll Sketch with a bin size of 8 bits
+ */
+ HLL_8;
private static final TgtHllType values[] = values();
+ /**
+ * Convert the typeId to the enum type
+ * @param typeId the given typeId
+ * @return the enum type
+ */
public static final TgtHllType fromOrdinal(final int typeId) {
return values[typeId];
}
diff --git a/src/main/java/org/apache/datasketches/kll/KllItemsSketch.java b/src/main/java/org/apache/datasketches/kll/KllItemsSketch.java
index 392da06..6fb9772 100644
--- a/src/main/java/org/apache/datasketches/kll/KllItemsSketch.java
+++ b/src/main/java/org/apache/datasketches/kll/KllItemsSketch.java
@@ -290,6 +290,10 @@
itemsSV = null;
}
+ /**
+ * Export the current sketch as a compact byte array.
+ * @return the current sketch as a compact byte array.
+ */
public byte[] toByteArray() {
return KllHelper.toByteArray(this, false);
}
diff --git a/src/main/java/org/apache/datasketches/kll/KllItemsSketchIterator.java b/src/main/java/org/apache/datasketches/kll/KllItemsSketchIterator.java
index 3a0a8da..02bda7a 100644
--- a/src/main/java/org/apache/datasketches/kll/KllItemsSketchIterator.java
+++ b/src/main/java/org/apache/datasketches/kll/KllItemsSketchIterator.java
@@ -23,6 +23,7 @@
/**
* Iterator over KllItemsSketch. The order is not defined.
+ * @param <T> the item class type
*/
public final class KllItemsSketchIterator<T> extends KllSketchIterator implements QuantilesGenericSketchIterator<T> {
private final Object[] quantiles;
diff --git a/src/main/java/org/apache/datasketches/kll/KllSketch.java b/src/main/java/org/apache/datasketches/kll/KllSketch.java
index 4ce15ab..c398ed8 100644
--- a/src/main/java/org/apache/datasketches/kll/KllSketch.java
+++ b/src/main/java/org/apache/datasketches/kll/KllSketch.java
@@ -218,6 +218,10 @@
return (wmem != null);
}
+ /**
+ * Returns true if this sketch is in a Compact Memory Format.
+ * @return true if this sketch is in a Compact Memory Format.
+ */
public boolean isCompactMemoryFormat() {
return hasMemory() && sketchStructure != UPDATABLE;
}
@@ -488,9 +492,18 @@
* Used to define the variable type of the current instance of this class.
*/
public enum SketchType {
- DOUBLES_SKETCH(Double.BYTES, "DoublesSketch"),
- FLOATS_SKETCH(Float.BYTES, "FloatsSketch"),
- ITEMS_SKETCH(0, "ItemsSketch");
+ /**
+ * KllDoublesSketch
+ */
+ DOUBLES_SKETCH(Double.BYTES, "KllDoublesSketch"),
+ /**
+ * KllFloatsSketch
+ */
+ FLOATS_SKETCH(Float.BYTES, "KllFloatsSketch"),
+ /**
+ * KllItemsSketch
+ */
+ ITEMS_SKETCH(0, "KllItemsSketch");
private int typeBytes;
private String name;
@@ -500,8 +513,16 @@
this.name = name;
}
+ /**
+ * Gets the item size in bytes. If the item is generic, this returns zero.
+ * @return the item size in bytes
+ */
public int getBytes() { return typeBytes; }
+ /**
+ * Get the name of the associated sketch
+ * @return the name of the associated sketch
+ */
public String getName() { return name; }
}
@@ -509,9 +530,13 @@
* Used primarily to define the structure of the serialized sketch. Also used by the Heap Sketch.
*/
public enum SketchStructure {
+ /** Compact Empty Structure */
COMPACT_EMPTY(PREAMBLE_INTS_EMPTY_SINGLE, SERIAL_VERSION_EMPTY_FULL),
+ /** Compact Single Item Structure */
COMPACT_SINGLE(PREAMBLE_INTS_EMPTY_SINGLE, SERIAL_VERSION_SINGLE),
+ /** Compact Full Preamble Structure */
COMPACT_FULL(PREAMBLE_INTS_FULL, SERIAL_VERSION_EMPTY_FULL),
+ /** Updatable Preamble Structure */
UPDATABLE(PREAMBLE_INTS_FULL, SERIAL_VERSION_UPDATABLE); //also used by the heap sketch.
private int preInts;
@@ -522,10 +547,24 @@
this.serVer = serVer;
}
+ /**
+ * gets the Preamble Integers for this Structure.
+ * @return the Preamble Integers for this Structure
+ */
public int getPreInts() { return preInts; }
+ /**
+ * gets the Serialization Version for this Structure.
+ * @return the Serialization Version for this Structure.
+ */
public int getSerVer() { return serVer; }
+ /**
+ * gets the SketchStructure given preInts and serVer.
+ * @param preInts the given preamble size in integers
+ * @param serVer the given Serialization Version
+ * @return the SketchStructure given preInts and serVer.
+ */
public static SketchStructure getSketchStructure(final int preInts, final int serVer) {
final SketchStructure[] ssArr = SketchStructure.values();
for (int i = 0; i < ssArr.length; i++) {
diff --git a/src/main/java/org/apache/datasketches/partitions/BoundsRule.java b/src/main/java/org/apache/datasketches/partitions/BoundsRule.java
index ecda05e..3cd3899 100644
--- a/src/main/java/org/apache/datasketches/partitions/BoundsRule.java
+++ b/src/main/java/org/apache/datasketches/partitions/BoundsRule.java
@@ -19,6 +19,10 @@
package org.apache.datasketches.partitions;
+/**
+ * This instructs the user about which of the upper and lower bounds of a partition definition row
+ * should be included with the returned data.
+ */
public enum BoundsRule {
/**
@@ -30,10 +34,12 @@
* Include only the upper bound but not the lower bound
*/
INCLUDE_UPPER,
+
/**
* Include only the lower bound but not the upper bound
*/
INCLUDE_LOWER,
+
/**
* Include none
*/
diff --git a/src/main/java/org/apache/datasketches/partitions/Partitioner.java b/src/main/java/org/apache/datasketches/partitions/Partitioner.java
index 66030fb..dd69f1e 100644
--- a/src/main/java/org/apache/datasketches/partitions/Partitioner.java
+++ b/src/main/java/org/apache/datasketches/partitions/Partitioner.java
@@ -162,12 +162,22 @@
/**
* Holds data for a Stack element
+ * @param <T> the item class type
*/
public static class StackElement<T> {
+ /** A reference to the relevant GenericPartitionBoundaries class */
public final GenericPartitionBoundaries<T> gpb;
+ /** The partition index */
public int part;
+ /** A brief string description of the partition and its hierarchy */
public String levelPartId;
+ /**
+ * Constructs this StackElement
+ * @param gpb the given GenericPartitionBoundarie reference
+ * @param part The partition index
+ * @param levelPartId A brief string description of the partition and its hierarchy
+ */
public StackElement(final GenericPartitionBoundaries<T> gpb, final int part, final String levelPartId) {
this.gpb = gpb;
this.part = part;
@@ -177,15 +187,26 @@
/**
* Defines a row for List of PartitionBounds.
+ * @param <T> the item class type
*/
public static class PartitionBoundsRow<T> {
+ /** The partition index */
public int part;
+ /** A brief string description of the partition and its hierarchy */
public String levelPartId;
+ /** The approximate number of items represented by this partition description row. */
public long approxNumDeltaItems;
+ /** The BoundsRule for this partition description row. */
public BoundsRule rule;
+ /** The lower bound value */
public T lowerBound;
+ /** The upper bound value */
public T upperBound;
+ /**
+ * The constructor for the StackElement class.
+ * @param se the given stack element.
+ */
public PartitionBoundsRow(final StackElement<T> se) {
final GenericPartitionBoundaries<T> gpb = se.gpb;
final QuantileSearchCriteria searchCrit = gpb.getSearchCriteria();
diff --git a/src/main/java/org/apache/datasketches/partitions/SketchFillRequest.java b/src/main/java/org/apache/datasketches/partitions/SketchFillRequest.java
index d005561..76e9d74 100644
--- a/src/main/java/org/apache/datasketches/partitions/SketchFillRequest.java
+++ b/src/main/java/org/apache/datasketches/partitions/SketchFillRequest.java
@@ -25,7 +25,8 @@
/**
* This is a callback request to the data source to fill a quantiles sketch,
* which is returned to the caller.
- *
+ * @param <T> the item class type
+ * @param <S> the sketch type
* @author Lee Rhodes
*/
public interface SketchFillRequest<T, S extends QuantilesGenericAPI<T> & PartitioningFeature<T>> {
diff --git a/src/main/java/org/apache/datasketches/quantilescommon/DoublesSortedViewIterator.java b/src/main/java/org/apache/datasketches/quantilescommon/DoublesSortedViewIterator.java
index da112dc..85bf96b 100644
--- a/src/main/java/org/apache/datasketches/quantilescommon/DoublesSortedViewIterator.java
+++ b/src/main/java/org/apache/datasketches/quantilescommon/DoublesSortedViewIterator.java
@@ -25,6 +25,12 @@
public final class DoublesSortedViewIterator extends SortedViewIterator {
private final double[] quantiles;
+ /**
+ * Constructor.
+ * @param quantiles the given array of quantiles, which must be ordered.
+ * @param cumWeights the given array of cumulative weights, which must be ordered, start with the value one, and
+ * the last value must be equal to N, the total number of items updated to the sketch.
+ */
public DoublesSortedViewIterator(final double[] quantiles, final long[] cumWeights) {
super(cumWeights);
this.quantiles = quantiles; //SpotBugs EI_EXPOSE_REP2 suppressed by FindBugsExcludeFilter
diff --git a/src/main/java/org/apache/datasketches/quantilescommon/FloatsSortedViewIterator.java b/src/main/java/org/apache/datasketches/quantilescommon/FloatsSortedViewIterator.java
index a40bace..09b45da 100644
--- a/src/main/java/org/apache/datasketches/quantilescommon/FloatsSortedViewIterator.java
+++ b/src/main/java/org/apache/datasketches/quantilescommon/FloatsSortedViewIterator.java
@@ -25,6 +25,12 @@
public final class FloatsSortedViewIterator extends SortedViewIterator {
private final float[] quantiles;
+ /**
+ * Constructor.
+ * @param quantiles the given array of quantiles, which must be ordered.
+ * @param cumWeights the given array of cumulative weights, which must be ordered, start with the value one, and
+ * the last value must be equal to N, the total number of items updated to the sketch.
+ */
public FloatsSortedViewIterator(final float[] quantiles, final long[] cumWeights) {
super(cumWeights);
this.quantiles = quantiles; //SpotBugs EI_EXPOSE_REP2 suppressed by FindBugsExcludeFilter
diff --git a/src/main/java/org/apache/datasketches/quantilescommon/GenericPartitionBoundaries.java b/src/main/java/org/apache/datasketches/quantilescommon/GenericPartitionBoundaries.java
index ee53e91..0eb44f3 100644
--- a/src/main/java/org/apache/datasketches/quantilescommon/GenericPartitionBoundaries.java
+++ b/src/main/java/org/apache/datasketches/quantilescommon/GenericPartitionBoundaries.java
@@ -27,6 +27,7 @@
/**
* This defines the returned results of the getParitionBoundaries() function and
* includes the basic methods needed to construct actual partitions.
+ * @param <T> the item class type
*/
public final class GenericPartitionBoundaries<T> {
private long totalN; //totalN of source sketch
@@ -40,6 +41,16 @@
private long[] numDeltaItems; //num of items in each partition
private int numPartitions; //num of partitions
+ /**
+ * Constructor.
+ * @param totalN the total number of items input to the sketch.
+ * @param boundaries The quantile boundaries between partitions
+ * @param natRanks The array of natural Ranks corresponding to the array of boundaries.
+ * @param normRanks The normalized Ranks corresponding to the array of boundaries.
+ * @param maxItem the maximum item of the stream.
+ * @param minItem the minimum item of the stream.
+ * @param searchCrit the user defined search criteria
+ */
public GenericPartitionBoundaries(
final long totalN,
final T[] boundaries,
diff --git a/src/main/java/org/apache/datasketches/quantilescommon/GenericSortedViewIterator.java b/src/main/java/org/apache/datasketches/quantilescommon/GenericSortedViewIterator.java
index fcfefa1..062c462 100644
--- a/src/main/java/org/apache/datasketches/quantilescommon/GenericSortedViewIterator.java
+++ b/src/main/java/org/apache/datasketches/quantilescommon/GenericSortedViewIterator.java
@@ -23,11 +23,17 @@
/**
* Iterator over quantile sketches of generic type.
- * @param <T> The generic quantile type
+ * @param <T> The generic item class type
*/
public class GenericSortedViewIterator<T> extends SortedViewIterator {
private final T[] quantiles;
+ /**
+ * Constructor
+ * @param quantiles the given array of quantiles
+ * @param cumWeights the array of cumulative weights, corresponding to the array of quantiles,
+ * starting with the value one and the end value must equal N, the total number of items input to the sketch.
+ */
public GenericSortedViewIterator(final T[] quantiles, final long[] cumWeights) {
super(cumWeights);
this.quantiles = quantiles; //SpotBugs EI_EXPOSE_REP2 suppressed by FindBugsExcludeFilter
diff --git a/src/main/java/org/apache/datasketches/quantilescommon/IncludeMinMax.java b/src/main/java/org/apache/datasketches/quantilescommon/IncludeMinMax.java
index 3394a09..203e338 100644
--- a/src/main/java/org/apache/datasketches/quantilescommon/IncludeMinMax.java
+++ b/src/main/java/org/apache/datasketches/quantilescommon/IncludeMinMax.java
@@ -27,36 +27,71 @@
*/
public class IncludeMinMax {
+ /** A simple structure to hold a pair of arrays */
public static class DoublesPair {
+ /** the array of quantiles */
public double[] quantiles;
+ /** the array of associated cumulative weights */
public long[] cumWeights;
+ /**
+ * Constructor.
+ * @param quantiles the array of quantiles
+ * @param cumWeights the array of associated cumulative weights
+ */
public DoublesPair(final double[] quantiles, final long[] cumWeights) {
this.quantiles = quantiles;
this.cumWeights = cumWeights;
}
}
+ /** A simple structure to hold a pair of arrays */
public static class FloatsPair {
+ /** The array of quantiles */
public float[] quantiles;
+ /** The array of associated cumulative weights */
public long[] cumWeights;
+ /**
+ * Constructor.
+ * @param quantiles the array of quantiles
+ * @param cumWeights the array of associated cumulative weights
+ */
public FloatsPair(final float[] quantiles, final long[] cumWeights) {
this.quantiles = quantiles;
this.cumWeights = cumWeights;
}
}
+ /**
+ * A simple structure to hold a pair of arrays
+ * @param <T> the item class type
+ */
public static class ItemsPair<T> {
+ /** The array of quantiles */
public T[] quantiles;
+ /** The array of associated cumulative weights */
public long[] cumWeights;
+ /**
+ * Constructor.
+ * @param quantiles the array of quantiles
+ * @param cumWeights the array of associated cumulative weights
+ */
public ItemsPair(final T[] quantiles, final long[] cumWeights) {
this.quantiles = quantiles;
this.cumWeights = cumWeights;
}
}
+ /**
+ * The logic to include the min and max of type double.
+ * @param quantilesIn The array of quantiles
+ * @param cumWeightsIn The array of associated cumulative weights
+ * @param maxItem the maximum item of the stream
+ * @param minItem the minimum item of the stream
+ * @return a DoublesPair
+ */
public static DoublesPair includeDoublesMinMax(
final double[] quantilesIn,
final long[] cumWeightsIn,
@@ -96,6 +131,14 @@
return new DoublesPair(adjQuantiles, adjCumWeights);
}
+ /**
+ * The logic to include the min and max of type float.
+ * @param quantilesIn The array of quantiles
+ * @param cumWeightsIn The array of associated cumulative weights
+ * @param maxItem the maximum item of the stream
+ * @param minItem the minimum item of the stream
+ * @return a FloatsPair
+ */
public static FloatsPair includeFloatsMinMax(
final float[] quantilesIn,
final long[] cumWeightsIn,
@@ -135,6 +178,16 @@
return new FloatsPair(adjQuantiles, adjCumWeights);
}
+ /**
+ * The logic to include the min and max of type T.
+ * @param quantilesIn The array of quantiles
+ * @param cumWeightsIn The array of associated cumulative weights
+ * @param maxItem the maximum item of the stream
+ * @param minItem the minimum item of the stream
+ * @param comparator a comparator for type T
+ * @param <T> the item class type
+ * @return an ItemsPair
+ */
@SuppressWarnings("unchecked")
public static <T> ItemsPair<T> includeItemsMinMax(
final T[] quantilesIn,
diff --git a/src/main/java/org/apache/datasketches/quantilescommon/ItemsSketchSortedView.java b/src/main/java/org/apache/datasketches/quantilescommon/ItemsSketchSortedView.java
index 4af4acd..5157838 100644
--- a/src/main/java/org/apache/datasketches/quantilescommon/ItemsSketchSortedView.java
+++ b/src/main/java/org/apache/datasketches/quantilescommon/ItemsSketchSortedView.java
@@ -49,9 +49,10 @@
private final int numRetItems;
/**
- * Construct Sorted View.
- * @param quantiles sorted array of quantiles
- * @param cumWeights sorted, monotonically increasing cumulative weights.
+ * Constructor.
+ * @param quantiles the given array of quantiles, which must be ordered.
+ * @param cumWeights the given array of cumulative weights, which must be ordered, start with the value one, and
+ * the last value must be equal to N, the total number of items updated to the sketch.
* @param sk the underlying quantile sketch.
*/
public ItemsSketchSortedView(
@@ -198,6 +199,12 @@
return index;
}
+ /**
+ * Gets an array of quantiles corresponding to the given array of ranks.
+ * @param ranks the given array of normalized ranks
+ * @param searchCrit The search criterion: either INCLUSIVE or EXCLUSIVE.
+ * @return an array of quantiles corresponding to the given array of ranks.
+ */
@SuppressWarnings("unchecked")
public T[] getQuantiles(final double[] ranks, final QuantileSearchCriteria searchCrit) {
if (isEmpty()) { throw new IllegalArgumentException(QuantilesAPI.EMPTY_MSG); }
diff --git a/src/main/java/org/apache/datasketches/quantilescommon/PartitioningFeature.java b/src/main/java/org/apache/datasketches/quantilescommon/PartitioningFeature.java
index 380f57f..5672c2a 100644
--- a/src/main/java/org/apache/datasketches/quantilescommon/PartitioningFeature.java
+++ b/src/main/java/org/apache/datasketches/quantilescommon/PartitioningFeature.java
@@ -23,6 +23,7 @@
/**
* This enables the special functions for performing efficient partitioning of massive data.
+ * @param <T> the item class type
*/
public interface PartitioningFeature<T> {
diff --git a/src/main/java/org/apache/datasketches/quantilescommon/QuantilesAPI.java b/src/main/java/org/apache/datasketches/quantilescommon/QuantilesAPI.java
index 0d02d2e..b70843b 100644
--- a/src/main/java/org/apache/datasketches/quantilescommon/QuantilesAPI.java
+++ b/src/main/java/org/apache/datasketches/quantilescommon/QuantilesAPI.java
@@ -202,6 +202,7 @@
* @author Kevin Lang
* @author Alexander Saydakov
*/
+@SuppressWarnings("javadoc")
public interface QuantilesAPI {
static String EMPTY_MSG = "The sketch must not be empty for this operation. ";
diff --git a/src/main/java/org/apache/datasketches/quantilescommon/QuantilesUtil.java b/src/main/java/org/apache/datasketches/quantilescommon/QuantilesUtil.java
index a35aa27..75798c2 100644
--- a/src/main/java/org/apache/datasketches/quantilescommon/QuantilesUtil.java
+++ b/src/main/java/org/apache/datasketches/quantilescommon/QuantilesUtil.java
@@ -209,8 +209,16 @@
return arr;
}
+ /** used in search to improve rounding over a wide dynamic range */
public static final double tailRoundingFactor = 1e7;
+ /**
+ * Computes the closest Natural Rank from a given Normalized Rank
+ * @param normalizedRank the given normalized rank
+ * @param totalN the total N
+ * @param searchCrit the search criterion.
+ * @return the closest Natural Rank from a given Normalized Rank
+ */
public static double getNaturalRank(
final double normalizedRank,
final long totalN,
diff --git a/src/main/java/org/apache/datasketches/sampling/EbppsItemsSketch.java b/src/main/java/org/apache/datasketches/sampling/EbppsItemsSketch.java
index f43c68c..b3aac54 100644
--- a/src/main/java/org/apache/datasketches/sampling/EbppsItemsSketch.java
+++ b/src/main/java/org/apache/datasketches/sampling/EbppsItemsSketch.java
@@ -46,7 +46,7 @@
*
* <p>The sample may be smaller than k and the resulting size of the sample potentially includes
* a probabilistic component, meaning the resulting sample size is not always constant.
- *
+ * @param <T> the item class type
* @author Jon Malkin
*/
public final class EbppsItemsSketch<T> {
diff --git a/src/main/java/org/apache/datasketches/tdigest/TDigestDouble.java b/src/main/java/org/apache/datasketches/tdigest/TDigestDouble.java
index 2327cb1..1e34085 100644
--- a/src/main/java/org/apache/datasketches/tdigest/TDigestDouble.java
+++ b/src/main/java/org/apache/datasketches/tdigest/TDigestDouble.java
@@ -43,6 +43,7 @@
*/
public final class TDigestDouble {
+ /** the default value of K if one is not specified */
public static final short DEFAULT_K = 200;
private boolean reverseMerge_;
diff --git a/src/main/java/org/apache/datasketches/theta/BitPacking.java b/src/main/java/org/apache/datasketches/theta/BitPacking.java
index 47e14d4..ca70daf 100644
--- a/src/main/java/org/apache/datasketches/theta/BitPacking.java
+++ b/src/main/java/org/apache/datasketches/theta/BitPacking.java
@@ -21,10 +21,20 @@
import org.apache.datasketches.common.SketchesArgumentException;
+/**
+ * Used as part of Theta compression.
+ */
public class BitPacking {
- public static void packBits(final long value, int bits, final byte[] buffer, int bufOffset,
- final int bitOffset) {
+ /**
+ * The bit packing operation
+ * @param value the value to pack
+ * @param bits number of bits to pack
+ * @param buffer the output byte array buffer
+ * @param bufOffset the byte offset in the buffer
+ * @param bitOffset the bit offset
+ */
+ public static void packBits(final long value, int bits, final byte[] buffer, int bufOffset, final int bitOffset) {
if (bitOffset > 0) {
final int chunkBits = 8 - bitOffset;
final int mask = (1 << chunkBits) - 1;
@@ -44,7 +54,16 @@
}
}
- public static void unpackBits(final long[] value, final int index, int bits, final byte[] buffer,
+ /**
+ * The unpacking operation
+ * @param value the output array
+ * @param index index of the value array
+ * @param bits the number of bits to unpack
+ * @param buffer the input packed buffer
+ * @param bufOffset the buffer offset
+ * @param bitOffset the bit offset
+ */
+ public static void unpackBits(final long[] value, final int index, int bits, final byte[] buffer,
int bufOffset,final int bitOffset) {
final int availBits = 8 - bitOffset;
final int chunkBits = availBits <= bits ? availBits : bits;
diff --git a/src/main/java/org/apache/datasketches/theta/CompactSketch.java b/src/main/java/org/apache/datasketches/theta/CompactSketch.java
index 29d02b5..1426368 100644
--- a/src/main/java/org/apache/datasketches/theta/CompactSketch.java
+++ b/src/main/java/org/apache/datasketches/theta/CompactSketch.java
@@ -249,6 +249,10 @@
return true;
}
+ /**
+ * gets the sketch as a compressed byte array
+ * @return the sketch as a compressed byte array
+ */
public byte[] toByteArrayCompressed() {
if (!isOrdered() || getRetainedEntries() == 0 || (getRetainedEntries() == 1 && !isEstimationMode())) {
return toByteArray();
diff --git a/src/main/java/org/apache/datasketches/thetacommon/SetOperationCornerCases.java b/src/main/java/org/apache/datasketches/thetacommon/SetOperationCornerCases.java
index 0a6bd8b..20dd6ee 100644
--- a/src/main/java/org/apache/datasketches/thetacommon/SetOperationCornerCases.java
+++ b/src/main/java/org/apache/datasketches/thetacommon/SetOperationCornerCases.java
@@ -28,9 +28,11 @@
* Simplifies and speeds up set operations by resolving specific corner cases.
* @author Lee Rhodes
*/
+@SuppressWarnings("javadoc")
public class SetOperationCornerCases {
private static final long MAX = Long.MAX_VALUE;
+ /** Intersection actions */
public enum IntersectAction {
DEGEN_MIN_0_F("D", "Degenerate{MinTheta, 0, F}"),
EMPTY_1_0_T("E", "Empty{1.0, 0, T}"),
@@ -53,6 +55,7 @@
}
}
+ /** A not B actions */
public enum AnotbAction {
SKETCH_A("A", "Sketch A Exactly"),
TRIM_A("TA", "Trim Sketch A by MinTheta"),
diff --git a/src/main/java/org/apache/datasketches/tuple/SerializerDeserializer.java b/src/main/java/org/apache/datasketches/tuple/SerializerDeserializer.java
index e4e6036..44d1d9c 100644
--- a/src/main/java/org/apache/datasketches/tuple/SerializerDeserializer.java
+++ b/src/main/java/org/apache/datasketches/tuple/SerializerDeserializer.java
@@ -31,6 +31,7 @@
/**
* Defines the sketch classes that this SerializerDeserializer can handle.
*/
+ @SuppressWarnings("javadoc")
public static enum SketchType { QuickSelectSketch, CompactSketch, ArrayOfDoublesQuickSelectSketch,
ArrayOfDoublesCompactSketch, ArrayOfDoublesUnion }
diff --git a/src/main/java/org/apache/datasketches/tuple/Util.java b/src/main/java/org/apache/datasketches/tuple/Util.java
index c4f8ff5..88fef26 100644
--- a/src/main/java/org/apache/datasketches/tuple/Util.java
+++ b/src/main/java/org/apache/datasketches/tuple/Util.java
@@ -153,6 +153,13 @@
return tmpSummaryArr;
}
+ /**
+ * Creates a new Summary Array with the specified length
+ * @param summaryArr example array, only used to obtain the component type. It has no data.
+ * @param length the desired length of the returned array.
+ * @param <S> the summary class type
+ * @return a new Summary Array with the specified length
+ */
@SuppressWarnings("unchecked")
public static <S extends Summary> S[] newSummaryArray(final S[] summaryArr, final int length) {
final Class<S> summaryType = (Class<S>) summaryArr.getClass().getComponentType();
