Improve javadoc

dogstatsd-http/core/src/main/java/com/datadoghq/dogstatsd/Sketch.java

@@ -13,11 +13,10 @@
  * Reusable DDSketch builder. Consumes a batch of observations and populates sum, min, max, count
  * and distribution bins accordingly.
  *
- * <p>This implementation maintains at most 4096 bins with 64-bit counters. Number of bins is a hard
- * limit and is enforced by the intake.
+ * <p>This implementation maintains at most 4096 bins with 64-bit counters.
  *
- * <p>Prioritizes accuracy of higher key bins (higher percentiles) over lower ones when number of
- * bins exceeds the limit.
+ * <p>Prioritizes accuracy of higher key bins (higher percentiles) over lower ones when the number
+ * of bins exceeds the limit.
  */
 public class Sketch {
     static final double gamma = 130.0 / 128;
@@ -59,6 +58,12 @@ static short key(double value) {
 
     /** Receives (key, count) pairs from {@link #bins(BinConsumer)}. */
     public interface BinConsumer {
+        /**
+         * Process one sketch bin.
+         *
+         * @param key a value that specifies the range of observations counted in this bin.
+         * @param count number of observations in the bin.
+         */
         void consumeBin(short key, long count);
     }
 
@@ -69,7 +74,11 @@ public int size() {
         return size;
     }
 
-    /** Feeds each populated bin to {@code consumer} in order. */
+    /**
+     * Feeds each populated bin to {@code consumer} in order.
+     *
+     * @param consumer a consumer to feed sketch bins to.
+     */
     public void bins(BinConsumer consumer) {
         int idx = head;
         for (int i = 0; i < size; i++) {
@@ -114,11 +123,13 @@ public long count() {
     /**
      * Builds the sketch from the given values.
      *
-     * @param observations the observations to include in the sketch
+     * @param observations the observations to include in the sketch.
      * @param sampleRate the sampling rate used to collect {@code observations}, in {@code (0, 1]}.
      *     Each observation is weighted by {@code 1 / sampleRate} when accumulating counts and sums.
      *     Rates below ~1.08e-19 saturate the per-observation weight; bin counts and the total
      *     {@code count} field saturate at {@link Long#MAX_VALUE} on overflow.
+     * @throws IllegalArgumentException if {@code sampleRate} is {@code NaN}, not positive, or
+     *     greater than 1.
      */
     public void build(long[] observations, double sampleRate) {
         validateSampleRate(sampleRate);
@@ -136,11 +147,13 @@ public void build(long[] observations, double sampleRate) {
     /**
      * Builds the sketch from the given values.
      *
-     * @param observations the observations to include in the sketch
+     * @param observations the observations to include in the sketch.
      * @param sampleRate the sampling rate used to collect {@code observations}, in {@code (0, 1]}.
      *     Each observation is weighted by {@code 1 / sampleRate} when accumulating counts and sums.
      *     Rates below ~1.08e-19 saturate the per-observation weight; bin counts and the total
      *     {@code count} field saturate at {@link Long#MAX_VALUE} on overflow.
+     * @throws IllegalArgumentException if {@code sampleRate} is {@code NaN}, not positive, or
+     *     greater than 1.
      */
     public void build(double[] observations, double sampleRate) {
         validateSampleRate(sampleRate);

dogstatsd-http/core/src/main/java/com/datadoghq/dogstatsd/http/DirectHttpClient.java

@@ -11,6 +11,7 @@
 import com.datadoghq.dogstatsd.http.serializer.PayloadBuilder;
 import com.datadoghq.dogstatsd.http.serializer.PayloadConsumer;
 import java.net.URI;
+import java.nio.BufferOverflowException;
 import java.util.List;
 import java.util.Objects;
 
@@ -35,6 +36,7 @@ public class DirectHttpClient {
      *
      * @param forwarder the forwarder used to send payloads, required.
      * @return a new builder.
+     * @throws NullPointerException if {@code forwarder} is null.
      */
     public static Builder builder(final Forwarder forwarder) {
         return new Builder(forwarder);
@@ -126,6 +128,7 @@ public DirectHttpClient build() {
      * @param value the gauge value.
      * @param ts the timestamp of the point in seconds since Unix epoch.
      * @param tags the tags to attach to the point.
+     * @throws BufferOverflowException if the encoded metric exceeds the maximum payload size.
      */
     public void gauge(String name, double value, long ts, List<String> tags) {
         seriesBuilder
@@ -139,12 +142,14 @@ public void gauge(String name, double value, long ts, List<String> tags) {
     /**
      * Records a count point.
      *
-     * <p>For compatibility with aggregated dogstatsd counts, assumes aggregation interval of 10s.
+     * <p>For compatibility with aggregated dogstatsd counts, assumes an aggregation interval of
+     * 10s.
      *
      * @param name the metric name, to which the client prefix is prepended.
      * @param value the count accumulated over the interval starting at {@code ts}.
      * @param ts the timestamp of the point in seconds since Unix epoch.
      * @param tags the tags to attach to the point.
+     * @throws BufferOverflowException if the encoded metric exceeds the maximum payload size.
      */
     public void count(String name, double value, long ts, List<String> tags) {
         seriesBuilder
@@ -163,6 +168,9 @@ public void count(String name, double value, long ts, List<String> tags) {
      * @param sampleRate the sampling rate used to collect {@code values}, in {@code (0, 1]}.
      * @param ts the timestamp of the point in seconds since Unix epoch.
      * @param tags the tags to attach to the point.
+     * @throws IllegalArgumentException if {@code sampleRate} is {@code NaN}, not positive, or
+     *     greater than 1.
+     * @throws BufferOverflowException if the encoded metric exceeds the maximum payload size.
      */
     public void distribution(
             String name, double[] values, double sampleRate, long ts, List<String> tags) {
@@ -174,7 +182,11 @@ private String prefixed(final String name) {
         return prefix.isEmpty() ? name : prefix + name;
     }
 
-    /** Completes any in-progress payloads and submits them to the forwarder. */
+    /**
+     * Completes any in-progress payloads and submits them to the forwarder.
+     *
+     * @throws BufferOverflowException if an encoded metric exceeds the maximum payload size.
+     */
     public void flush() {
         seriesBuilder.close();
         sketchesBuilder.close();

dogstatsd-http/core/src/main/java/com/datadoghq/dogstatsd/http/ForwarderContext.java

@@ -31,6 +31,12 @@ public static Builder builder() {
         return new Builder();
     }
 
+    /**
+     * Returns the base URI that per-payload URIs are resolved against. Always ends with {@code /}
+     * so that it acts as a prefix for {@link URI#resolve}.
+     *
+     * @return the base URI, never null.
+     */
     public URI baseUri() {
         return baseUri;
     }
@@ -55,9 +61,11 @@ public String externalData() {
     }
 
     /**
-     * Returns new instance with default settings.
+     * Returns a new instance with default settings.
      *
-     * @return new default instance.
+     * @return a new default instance.
+     * @throws IllegalStateException if {@code DD_DOGSTATSD_HTTP_URL} is not defined.
+     * @throws IllegalArgumentException if the base URI is malformed.
      */
     public static ForwarderContext defaults() {
         return builder().build();
@@ -112,14 +120,20 @@ public Builder originDetectionEnabled(final boolean val) {
          * Sets the base URI the series and sketches endpoints are resolved against. Defaults to the
          * value of the {@code DD_DOGSTATSD_HTTP_URL} environment variable.
          *
-         * @param val the base URI, or null to use the default.
+         * @param uri the base URI, or null to use the default.
          * @return this builder.
          */
         public Builder baseUri(final String uri) {
             baseUri = uri;
             return this;
         }
 
+        /**
+         * Use the supplied map instead of OS environment variables.
+         *
+         * @param val the environment map.
+         * @return this builder.
+         */
         public Builder environment(final Map<String, String> val) {
             env = new EnvMap(val);
             return this;
@@ -134,7 +148,9 @@ Builder cgroupReader(final CgroupReader val) {
          * Builds the context, running detection for any value not set explicitly.
          *
          * @return a new context.
-         * @throws URISyntaxException if baseUri value is not a valid URI.
+         * @throws IllegalStateException if no base URI was set with {@link #baseUri} and {@code
+         *     DD_DOGSTATSD_HTTP_URL} is not defined.
+         * @throws IllegalArgumentException if the base URI is malformed.
          */
         public ForwarderContext build() {
             String local = localData;

dogstatsd-http/core/src/main/java/com/datadoghq/dogstatsd/http/serializer/Buffer.java

@@ -41,7 +41,7 @@ void clear() {
         size = 0;
     }
 
-    /** Return true if buf is null or empty */
+    /** Return true if buf is null or empty. */
     static boolean isEmpty(Buffer buf) {
         return buf == null || buf.size == 0;
     }

dogstatsd-http/core/src/main/java/com/datadoghq/dogstatsd/http/serializer/Metric.java

@@ -42,6 +42,7 @@ public T setTags(List<String> tags) {
      * @param resources List of even length, containing zero or more (type, name) pairs, or null for
      *     no resources.
      * @return This.
+     * @throws IllegalArgumentException if {@code resources} has an odd number of elements.
      */
     public T setResources(List<String> resources) {
         if (resources != null && resources.size() % 2 != 0) {
@@ -100,7 +101,13 @@ void encodeDependentFields() {
         pb.encodeOrigin(origin);
     }
 
-    /** Finish this timeseries and add it to the payload. */
+    /**
+     * Finish this timeseries and add it to the payload.
+     *
+     * @throws java.nio.BufferOverflowException if the encoded metric exceeds the maximum payload
+     *     size. The in-progress metric is discarded, so no {@link PayloadBuilder#resetMetric()} is
+     *     needed before encoding further metrics.
+     */
     public void close() {
         pb.endMetric();
     }

dogstatsd-http/core/src/main/java/com/datadoghq/dogstatsd/http/serializer/PayloadBuilder.java

@@ -135,7 +135,7 @@ public void encode(Origin o) {
     Metric<?> metricInProgress;
 
     /**
-     * Create new PayloadBuilder.
+     * Create a new PayloadBuilder.
      *
      * @param consumer Is given payloads one by one as they are finished.
      */
@@ -145,12 +145,13 @@ public PayloadBuilder(PayloadConsumer consumer) {
     }
 
     /**
-     * Begin encoding new count metric.
+     * Begin encoding a new count metric.
      *
      * <p>Only one metric can be encoded at a time.
      *
      * @param name Name of the metric.
-     * @return Builder instance.
+     * @return New builder instance.
+     * @throws BufferOverflowException if finishing the previous metric overflows the payload.
      */
     public ScalarMetric count(String name) {
         ScalarMetric m = new ScalarMetric(this, 1, name);
@@ -159,12 +160,13 @@ public ScalarMetric count(String name) {
     }
 
     /**
-     * Begin encoding new rate metric.
+     * Begin encoding a new rate metric.
      *
      * <p>Only one metric can be encoded at a time.
      *
      * @param name Name of the metric.
      * @return New builder instance.
+     * @throws BufferOverflowException if finishing the previous metric overflows the payload.
      */
     public ScalarMetric rate(String name) {
         ScalarMetric m = new ScalarMetric(this, 2, name);
@@ -173,12 +175,13 @@ public ScalarMetric rate(String name) {
     }
 
     /**
-     * Begin encoding new gauge metric.
+     * Begin encoding a new gauge metric.
      *
      * <p>Only one metric can be encoded at a time.
      *
      * @param name Name of the metric.
      * @return New builder instance.
+     * @throws BufferOverflowException if finishing the previous metric overflows the payload.
      */
     public ScalarMetric gauge(String name) {
         ScalarMetric m = new ScalarMetric(this, 3, name);
@@ -187,12 +190,13 @@ public ScalarMetric gauge(String name) {
     }
 
     /**
-     * Begin encoding new sketch metric.
+     * Begin encoding a new sketch metric.
      *
      * <p>Only one metric can be encoded at a time.
      *
      * @param name Name of the metric.
      * @return New builder instance.
+     * @throws BufferOverflowException if finishing the previous metric overflows the payload.
      */
     public SketchMetric sketch(String name) {
         SketchMetric m = new SketchMetric(this, 4, name);
@@ -305,7 +309,11 @@ void flushPayload() {
         timestampsDelta.clear();
     }
 
-    /** Finish any pending data. */
+    /**
+     * Finish any pending data.
+     *
+     * @throws BufferOverflowException if finishing the in-progress metric overflows the payload.
+     */
     public void close() {
         endMetric();
         flushPayload();

dogstatsd-http/core/src/main/java/com/datadoghq/dogstatsd/http/serializer/PayloadConsumer.java

@@ -10,7 +10,7 @@
 /** Consumes payloads from the PayloadBuilder. */
 public interface PayloadConsumer {
     /**
-     * Called when payload builder finishes another payload.
+     * Called when the payload builder finishes another payload.
      *
      * @param payload Completed payload.
      */

dogstatsd-http/core/src/main/java/com/datadoghq/dogstatsd/http/serializer/ScalarMetric.java

@@ -19,7 +19,7 @@ protected ScalarMetric self() {
     }
 
     /**
-     * Add new data point to the timeseries.
+     * Add a new data point to the timeseries.
      *
      * @param timestamp Timestamp of the point in seconds since Unix epoch.
      * @param value Metric value at timestamp.

dogstatsd-http/core/src/main/java/com/datadoghq/dogstatsd/http/serializer/SketchMetric.java

@@ -53,6 +53,9 @@ protected SketchMetric self() {
      * @param timestamp Timestamp of the point in seconds since Unix epoch.
      * @param sketch Sketch supplying the summary statistics and bin distribution.
      * @return This.
+     * @throws BufferOverflowException if the sketch's bin data alone would exceed the maximum
+     *     payload size. The metric is no longer valid; call {@link PayloadBuilder#resetMetric()}
+     *     before encoding any further metrics.
      */
     public SketchMetric addPoint(long timestamp, Sketch sketch) {
         // Skip doing the work if just the bin data would exceed payload size limit.