From abad8eeb95af17717778e42cb1129ab7a7dfc64c Mon Sep 17 00:00:00 2001
From: "vladimir.bukhtoyarov" <jsecoder@mail.ru>
Date: Tue, 8 Nov 2016 13:48:12 +0300
Subject: [PATCH] prepare release documentation

---
 README.md                                     |  3 +-
 pom.xml                                       |  2 +-
 .../metricscore/hdr/top/TopMetricSet.java     | 32 +++++++++++++++++++
 3 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 6074fa0..02689d4 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,8 @@
 The library contains collection of advanced metrics which missed in the original [Metrics Core](https://dropwizard.github.io/metrics/3.1.0/manual/core/) such as:
 * Rolling time window counters. [See documentation for counters](counters.md).
 * Rolling time window hit-ratio. [See documentation for hit-ratio](hit-ratio.md).
-* Histograms with loss-less capturing. [See documentation for histograms](histograms.md).
+* Top of queries by latency. [See documentation for top](top.md).
+* Loss-less capturing histograms(based on HdrHistogram). [See documentation for histograms](histograms.md).
 
 ## Build status
 [![Build Status](https://travis-ci.org/vladimir-bukhtoyarov/metrics-core-hdr.svg?branch=master)](https://travis-ci.org/vladimir-bukhtoyarov/metrics-core-hdr)
diff --git a/pom.xml b/pom.xml
index 879192e..edeba43 100644
--- a/pom.xml
+++ b/pom.xml
@@ -22,7 +22,7 @@
 
     <groupId>com.github.metrics-core-addons</groupId>
     <artifactId>metrics-core-hdr</artifactId>
-    <version>1.5.0</version>
+    <version>1.6.0</version>
 
     <packaging>jar</packaging>
     <name>Metrics-Core-HDR</name>
diff --git a/src/main/java/com/github/metricscore/hdr/top/TopMetricSet.java b/src/main/java/com/github/metricscore/hdr/top/TopMetricSet.java
index bb03114..a7bc1c5 100644
--- a/src/main/java/com/github/metricscore/hdr/top/TopMetricSet.java
+++ b/src/main/java/com/github/metricscore/hdr/top/TopMetricSet.java
@@ -28,11 +28,43 @@
 import java.util.Map;
 import java.util.concurrent.TimeUnit;
 
+/**
+ * The adapter to use {@link Top} with {@link com.codahale.metrics.MetricRegistry}.
+ * <p>
+ * <p><b>Sample Usage:</b>
+ * <pre> {@code
+ *
+ *  Top top = Top.builder(3).resetAllPositionsOnSnapshot().build();
+ *  MetricSet metricSet = new TopMetricSet("my-top", top, TimeUnit.MILLISECONDS, 5);
+ *  registry.registerAll(metricSet);
+ * }</pre>
+ * The code above creates 7 gauges with following names:
+ * <ul>
+ *   <li>my-top.latencyUnit</li>
+ *   <li>my-top.0.latency</li>
+ *   <li>my-top.0.description</li>
+ *   <li>my-top.1.latency</li>
+ *   <li>my-top.1.description</li>
+ *   <li>my-top.2.latency</li>
+ *   <li>my-top.2.description</li>
+ * </ul>
+ * The "latency" gauges have {@link BigDecimal} type, the "latencyUnit" and "description" gauges have {@link String} type.
+ * The number in the gauge name represents position in the top in descending order, the "0" is the slowest query.
+ * </p>
+ */
 public class TopMetricSet implements MetricSet {
 
     private final BigDecimal zero;
     private final Map<String, Metric> gauges;
 
+    /**
+     * Creates new collection of gauges which compatible with {@link com.codahale.metrics.MetricRegistry}.
+     *
+     * @param name the name prefix for each gauge
+     * @param top the target {@link Top}
+     * @param latencyUnit the time unit to convert latency
+     * @param digitsAfterDecimalPoint the number of digits after decimal point
+     */
     public TopMetricSet(String name, Top top, TimeUnit latencyUnit, int digitsAfterDecimalPoint) {
         if (name == null) {
             throw new IllegalArgumentException("name should not be null");