This is an automated email from the ASF dual-hosted git repository. leerho pushed a commit to branch improve_javadocs in repository https://gitbox.apache.org/repos/asf/datasketches-java.git
commit 52d29de27c1abb00b15eef4956bedd3fb4ab1912 Author: Lee Rhodes <[email protected]> AuthorDate: Sun Apr 21 18:43:02 2024 -0700 Improved javadocs for main code. --- .../cpc/CompressionCharacterization.java | 15 ++++++ .../filters/bloomfilter/BloomFilter.java | 18 +++++++- .../filters/bloomfilter/DirectBitArrayR.java | 3 ++ .../org/apache/datasketches/hll/TgtHllType.java | 19 +++++++- .../apache/datasketches/kll/KllItemsSketch.java | 4 ++ .../datasketches/kll/KllItemsSketchIterator.java | 1 + .../org/apache/datasketches/kll/KllSketch.java | 45 ++++++++++++++++-- .../apache/datasketches/partitions/BoundsRule.java | 6 +++ .../datasketches/partitions/Partitioner.java | 21 +++++++++ .../datasketches/partitions/SketchFillRequest.java | 3 +- .../quantilescommon/DoublesSortedViewIterator.java | 6 +++ .../quantilescommon/FloatsSortedViewIterator.java | 6 +++ .../GenericPartitionBoundaries.java | 11 +++++ .../quantilescommon/GenericSortedViewIterator.java | 8 +++- .../quantilescommon/IncludeMinMax.java | 53 ++++++++++++++++++++++ .../quantilescommon/ItemsSketchSortedView.java | 13 ++++-- .../quantilescommon/PartitioningFeature.java | 1 + .../datasketches/quantilescommon/QuantilesAPI.java | 1 + .../quantilescommon/QuantilesUtil.java | 8 ++++ .../datasketches/sampling/EbppsItemsSketch.java | 2 +- .../apache/datasketches/tdigest/TDigestDouble.java | 1 + .../org/apache/datasketches/theta/BitPacking.java | 25 ++++++++-- .../apache/datasketches/theta/CompactSketch.java | 4 ++ .../thetacommon/SetOperationCornerCases.java | 3 ++ .../datasketches/tuple/SerializerDeserializer.java | 1 + .../java/org/apache/datasketches/tuple/Util.java | 7 +++ 26 files changed, 270 insertions(+), 15 deletions(-) diff --git a/src/main/java/org/apache/datasketches/cpc/CompressionCharacterization.java b/src/main/java/org/apache/datasketches/cpc/CompressionCharacterization.java index 962b2882..4f0a9335 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 @@ public class CompressionCharacterization { 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 @@ public class CompressionCharacterization { 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 0c957ce9..3ea73b9b 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 @@ import org.apache.datasketches.memory.XxHash; * 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 @@ public final class BloomFilter { 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 19c495af..8acc36be 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.common.SketchesReadOnlyException; 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 a0ee79a4..a5dc395c 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 @@ package org.apache.datasketches.hll; * </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 392da067..6fb9772f 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 @@ public abstract class KllItemsSketch<T> extends KllSketch implements QuantilesGe 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 3a0a8da0..02bda7a2 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 @@ import org.apache.datasketches.quantilescommon.QuantilesGenericSketchIterator; /** * 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 4ce15aba..c398ed8c 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 @@ public abstract class KllSketch implements QuantilesAPI { 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 @@ public abstract class KllSketch implements QuantilesAPI { * 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 @@ public abstract class KllSketch implements QuantilesAPI { 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 @@ public abstract class KllSketch implements QuantilesAPI { * 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 @@ public abstract class KllSketch implements QuantilesAPI { 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 ecda05e1..3cd38996 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 @@ public enum BoundsRule { * 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 66030fb2..dd69f1ec 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 @@ public class Partitioner<T, S extends QuantilesGenericAPI<T> & PartitioningFeatu /** * 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 @@ public class Partitioner<T, S extends QuantilesGenericAPI<T> & PartitioningFeatu /** * 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 d005561d..76e9d745 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 @@ import org.apache.datasketches.quantilescommon.QuantilesGenericAPI; /** * 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 da112dc2..85bf96b6 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 @@ package org.apache.datasketches.quantilescommon; 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 a40bacef..09b45da0 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 @@ package org.apache.datasketches.quantilescommon; 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 ee53e910..0eb44f3e 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 @@ import org.apache.datasketches.common.SketchesStateException; /** * 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 @@ public final class GenericPartitionBoundaries<T> { 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 fcfefa12..062c462d 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 @@ import static org.apache.datasketches.quantilescommon.QuantileSearchCriteria.INC /** * 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 3394a096..203e338d 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 @@ import java.util.Comparator; */ 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 @@ public class IncludeMinMax { 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 @@ public class IncludeMinMax { 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 4af4acd5..51578382 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 @@ public class ItemsSketchSortedView<T> implements GenericSortedView<T> { 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 @@ public class ItemsSketchSortedView<T> implements GenericSortedView<T> { 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 380f57f0..5672c2a0 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 @@ import static org.apache.datasketches.quantilescommon.QuantileSearchCriteria.INC /** * 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 0d02d2ec..b70843bb 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 @@ package org.apache.datasketches.quantilescommon; * @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 a35aa27c..75798c20 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 @@ public final class QuantilesUtil { 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 f43c68cc..b3aac54b 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 @@ import org.apache.datasketches.memory.WritableMemory; * * <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 2327cb13..1e340851 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 @@ import org.apache.datasketches.quantilescommon.QuantilesAPI; */ 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 47e14d4e..ca70dafa 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 @@ package org.apache.datasketches.theta; 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 class BitPacking { } } - 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 29d02b5c..1426368f 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 @@ public abstract class CompactSketch extends Sketch { 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 0a6bd8bf..20dd6ee7 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 @@ import org.apache.datasketches.common.SketchesArgumentException; * 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 @@ public class SetOperationCornerCases { } } + /** 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 e4e60366..44d1d9cc 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 @@ public final class SerializerDeserializer { /** * 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 c4f8ff55..88fef260 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 @@ public final class Util { 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(); --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
