Add Javadocs (issue micrometer-metrics#372)

micrometer-core/src/main/java/io/micrometer/core/instrument/Clock.java

@@ -17,6 +17,12 @@
 
 import io.micrometer.core.instrument.step.StepLong;
 
+/**
+ * Used to measure absolute and relative time.
+ *
+ * @see MockClock for a clock that can be manually advanced for use in tests.
+ * @author Jon Schneider
+ */
 public interface Clock {
     Clock SYSTEM = new Clock() {
         @Override

micrometer-core/src/main/java/io/micrometer/core/instrument/CountAtValue.java

@@ -19,6 +19,11 @@
 
 import java.util.concurrent.TimeUnit;
 
+/**
+ * The count accumulated to a histogram bucket.
+ *
+ * @author Trustin Heuiseung Lee
+ */
 public final class CountAtValue {
 
     private final long value;

micrometer-core/src/main/java/io/micrometer/core/instrument/Counter.java

@@ -58,11 +58,16 @@ default Type type() {
         return Type.Counter;
     }
 
+    /**
+     * Fluent builder for counters.
+     */
     class Builder {
         private final String name;
         private final List<Tag> tags = new ArrayList<>();
+
         @Nullable
         private String description;
+
         @Nullable
         private String baseUnit;
 
@@ -77,26 +82,51 @@ public Builder tags(String... tags) {
             return tags(Tags.of(tags));
         }
 
+        /**
+         * @param tags Tags to add to the eventual counter.
+         * @return The counter builder with added tags.
+         */
         public Builder tags(Iterable<Tag> tags) {
             tags.forEach(this.tags::add);
             return this;
         }
 
+        /**
+         * @param key   The tag key.
+         * @param value The tag value.
+         * @return The counter builder with a single added tag.
+         */
         public Builder tag(String key, String value) {
             tags.add(Tag.of(key, value));
             return this;
         }
 
+        /**
+         * @param description Description text of the eventual counter.
+         * @return The counter builder with added description.
+         */
         public Builder description(@Nullable String description) {
             this.description = description;
             return this;
         }
 
+        /**
+         * @param unit Base unit of the eventual counter.
+         * @return The counter builder with added base unit.
+         */
         public Builder baseUnit(@Nullable String unit) {
             this.baseUnit = unit;
             return this;
         }
 
+        /**
+         * Add the counter to a single registry, or return an existing counter in that registry. The returned
+         * counter will be unique for each registry, but each registry is guaranteed to only create one counter
+         * for the same combination of name and tags.
+         *
+         * @param registry A registry to add the counter to, if it doesn't already exist.
+         * @return A new or existing counter.
+         */
         public Counter register(MeterRegistry registry) {
             return registry.counter(new Meter.Id(name, tags, baseUnit, description, Type.Counter));
         }

micrometer-core/src/main/java/io/micrometer/core/instrument/DistributionSummary.java

@@ -26,6 +26,8 @@
 /**
  * Track the sample distribution of events. An example would be the response sizes for requests
  * hitting and http server.
+ *
+ * @author Jon Schneider
  */
 public interface DistributionSummary extends Meter {
 
@@ -77,14 +79,19 @@ default Iterable<Measurement> measure() {
         );
     }
 
+    /**
+     * Fluent builder for distribution summaries.
+     */
     class Builder {
         private final String name;
         private final List<Tag> tags = new ArrayList<>();
+        private HistogramConfig.Builder histogramConfigBuilder = HistogramConfig.builder();
+
         @Nullable
         private String description;
+
         @Nullable
         private String baseUnit;
-        private HistogramConfig.Builder histogramConfigBuilder = HistogramConfig.builder();
 
         private Builder(String name) {
             this.name = name;
@@ -97,21 +104,38 @@ public Builder tags(String... tags) {
             return tags(Tags.of(tags));
         }
 
+        /**
+         * @param tags Tags to add to the eventual distribution summary.
+         * @return The distribution summary builder with added tags.
+         */
         public Builder tags(Iterable<Tag> tags) {
             tags.forEach(this.tags::add);
             return this;
         }
 
+        /**
+         * @param key   The tag key.
+         * @param value The tag value.
+         * @return The distribution summary builder with a single added tag.
+         */
         public Builder tag(String key, String value) {
             tags.add(Tag.of(key, value));
             return this;
         }
 
+        /**
+         * @param description Description text of the eventual distribution summary.
+         * @return The distribution summary builder with added description.
+         */
         public Builder description(@Nullable String description) {
             this.description = description;
             return this;
         }
 
+        /**
+         * @param unit Base unit of the eventual distribution summary.
+         * @return The distribution summary builder with added base unit.
+         */
         public Builder baseUnit(@Nullable String unit) {
             this.baseUnit = unit;
             return this;
@@ -134,6 +158,8 @@ public Builder publishPercentiles(@Nullable double... percentiles) {
          * Adds histogram buckets usable for generating aggregable percentile approximations in monitoring
          * systems that have query facilities to do so (e.g. Prometheus' {@code histogram_quantile},
          * Atlas' {@code :percentiles}).
+         *
+         * @return This builder.
          */
         public Builder publishPercentileHistogram() {
             return publishPercentileHistogram(true);
@@ -143,6 +169,9 @@ public Builder publishPercentileHistogram() {
          * Adds histogram buckets usable for generating aggregable percentile approximations in monitoring
          * systems that have query facilities to do so (e.g. Prometheus' {@code histogram_quantile},
          * Atlas' {@code :percentiles}).
+         *
+         * @param enabled Value determining whether histgoram
+         * @return This builder.
          */
         public Builder publishPercentileHistogram(@Nullable Boolean enabled) {
             this.histogramConfigBuilder.percentilesHistogram(enabled);
@@ -155,32 +184,73 @@ public Builder publishPercentileHistogram(@Nullable Boolean enabled) {
          * other buckets used to generate aggregable percentile approximations.
          *
          * @param sla Publish SLA boundaries in the set of histogram buckets shipped to the monitoring system.
+         * @return This builder.
          */
         public Builder sla(@Nullable long... sla) {
             this.histogramConfigBuilder.sla(sla);
             return this;
         }
 
+        /**
+         * Sets the minimum value that this distribution summary is expected to observe. Sets a lower bound
+         * on histogram buckets that are shipped to monitoring systems that support aggregable percentile approximations.
+         *
+         * @param min The minimum value that this distribution summary is expected to observe.
+         * @return This builder.
+         */
         public Builder minimumExpectedValue(@Nullable Long min) {
             this.histogramConfigBuilder.minimumExpectedValue(min);
             return this;
         }
 
+        /**
+         * Sets the maximum value that this distribution summary is expected to observe. Sets an upper bound
+         * on histogram buckets that are shipped to monitoring systems that support aggregable percentile approximations.
+         *
+         * @param max The maximum value that this distribution summary is expected to observe.
+         * @return This builder.
+         */
         public Builder maximumExpectedValue(@Nullable Long max) {
             this.histogramConfigBuilder.maximumExpectedValue(max);
             return this;
         }
 
+        /**
+         * Statistics emanating from a distribution summary like max, percentiles, and histogram counts decay over time to
+         * give greater weight to recent samples (exception: histogram counts are cumulative for those systems that expect cumulative
+         * histogram buckets). Samples are accumulated to such statistics in ring buffers which rotate after
+         * this expiry, with a buffer length of {@link #histogramBufferLength(Integer)}.
+         *
+         * @param expiry The amount of time samples are accumulated to a histogram before it is reset and rotated.
+         * @return This builder.
+         */
         public Builder histogramExpiry(@Nullable Duration expiry) {
             this.histogramConfigBuilder.histogramExpiry(expiry);
             return this;
         }
 
+        /**
+         * Statistics emanating from a distribution summary like max, percentiles, and histogram counts decay over time to
+         * give greater weight to recent samples (exception: histogram counts are cumulative for those systems that expect cumulative
+         * histogram buckets). Samples are accumulated to such statistics in ring buffers which rotate after
+         * {@link #histogramExpiry(Duration)}, with this buffer length.
+         *
+         * @param bufferLength The number of histograms to keep in the ring buffer.
+         * @return This builder.
+         */
         public Builder histogramBufferLength(@Nullable Integer bufferLength) {
             this.histogramConfigBuilder.histogramBufferLength(bufferLength);
             return this;
         }
 
+        /**
+         * Add the distribution summary to a single registry, or return an existing distribution summary in that registry. The returned
+         * distribution summary will be unique for each registry, but each registry is guaranteed to only create one distribution summary
+         * for the same combination of name and tags.
+         *
+         * @param registry A registry to add the distribution summary to, if it doesn't already exist.
+         * @return A new or existing distribution summary.
+         */
         public DistributionSummary register(MeterRegistry registry) {
             return registry.summary(new Meter.Id(name, tags, baseUnit, description, Type.DistributionSummary), histogramConfigBuilder.build());
         }

micrometer-core/src/main/java/io/micrometer/core/instrument/FunctionCounter.java

@@ -47,6 +47,11 @@ default Meter.Type type() {
         return Meter.Type.Counter;
     }
 
+    /**
+     * Fluent builder for function counters.
+     *
+     * @param <T> The type of the state object from which the counter value is extracted.
+     */
     class Builder<T> {
         private final String name;
         private final T obj;
@@ -70,26 +75,51 @@ public Builder<T> tags(String... tags) {
             return tags(Tags.of(tags));
         }
 
+        /**
+         * @param tags Tags to add to the eventual meter.
+         * @return The function counter builder with added tags.
+         */
         public Builder<T> tags(Iterable<Tag> tags) {
             tags.forEach(this.tags::add);
             return this;
         }
 
+        /**
+         * @param key   The tag key.
+         * @param value The tag value.
+         * @return The function counter builder with a single added tag.
+         */
         public Builder<T> tag(String key, String value) {
             tags.add(Tag.of(key, value));
             return this;
         }
 
+        /**
+         * @param description Description text of the eventual function counter.
+         * @return The function counter builder with added description.
+         */
         public Builder<T> description(@Nullable String description) {
             this.description = description;
             return this;
         }
 
+        /**
+         * @param unit Base unit of the eventual counter.
+         * @return The counter builder with added base unit.
+         */
         public Builder<T> baseUnit(@Nullable String unit) {
             this.baseUnit = unit;
             return this;
         }
 
+        /**
+         * Add the function counter to a single registry, or return an existing function counter in that registry. The returned
+         * function counter will be unique for each registry, but each registry is guaranteed to only create one function counter
+         * for the same combination of name and tags.
+         *
+         * @param registry A registry to add the function counter to, if it doesn't already exist.
+         * @return A new or existing function counter.
+         */
         public FunctionCounter register(MeterRegistry registry) {
             return registry.more().counter(new Meter.Id(name, tags, baseUnit, description, Type.Counter), obj, f);
         }

micrometer-core/src/main/java/io/micrometer/core/instrument/FunctionTimer.java

@@ -55,17 +55,21 @@ default Iterable<Measurement> measure() {
         );
     }
 
+    /**
+     * Fluent builder for function timer.
+     *
+     * @param <T> The type of the state object from which the timer values are extracted.
+     */
     class Builder<T> {
         private final String name;
         private final T obj;
         private final ToLongFunction<T> countFunction;
         private final ToDoubleFunction<T> totalTimeFunction;
         private final TimeUnit totalTimeFunctionUnits;
         private final List<Tag> tags = new ArrayList<>();
+
         @Nullable
         private String description;
-        @Nullable
-        private String baseUnit;
 
         private Builder(String name, T obj,
                         ToLongFunction<T> countFunction,
@@ -85,28 +89,44 @@ public Builder<T> tags(String... tags) {
             return tags(Tags.of(tags));
         }
 
+        /**
+         * @param tags Tags to add to the eventual meter.
+         * @return The function timer builder with added tags.
+         */
         public Builder<T> tags(Iterable<Tag> tags) {
             tags.forEach(this.tags::add);
             return this;
         }
 
+        /**
+         * @param key   The tag key.
+         * @param value The tag value.
+         * @return The function timer builder with a single added tag.
+         */
         public Builder<T> tag(String key, String value) {
             tags.add(Tag.of(key, value));
             return this;
         }
 
+        /**
+         * @param description Description text of the eventual function timer.
+         * @return The function timer builder with added description.
+         */
         public Builder<T> description(@Nullable String description) {
             this.description = description;
             return this;
         }
 
-        public Builder<T> baseUnit(@Nullable String unit) {
-            this.baseUnit = unit;
-            return this;
-        }
-
+        /**
+         * Add the function timer to a single registry, or return an existing function timer in that registry. The returned
+         * function timer will be unique for each registry, but each registry is guaranteed to only create one function timer
+         * for the same combination of name and tags.
+         *
+         * @param registry A registry to add the function timer to, if it doesn't already exist.
+         * @return A new or existing function timer.
+         */
         public FunctionTimer register(MeterRegistry registry) {
-            return registry.more().timer(new Meter.Id(name, tags, baseUnit, description, Type.Timer), obj, countFunction, totalTimeFunction,
+            return registry.more().timer(new Meter.Id(name, tags, null, description, Type.Timer), obj, countFunction, totalTimeFunction,
                 totalTimeFunctionUnits);
         }
     }