Adding descriptions to package-info.java. Fixes #207

Signed-off-by: Raymond Lam <lamr@ca.ibm.com>

api/src/main/java/org/eclipse/microprofile/metrics/annotation/package-info.java

@@ -1,6 +1,6 @@
 /*
  **********************************************************************
- * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright (c) 2017, 2018 Contributors to the Eclipse Foundation
  *
  * See the NOTICES file(s) distributed with this work for additional
  * information regarding copyright ownership.
@@ -19,6 +19,76 @@
  *
  * SPDX-License-Identifier: Apache-2.0
  **********************************************************************/
+
+/**
+ * <p>
+ * This package contains the annotations used for MicroProfile Metrics.
+ * 
+ * <h2>Metric Annotation</h2>
+ * <p>
+ * The {@link org.eclipse.microprofile.metrics.annotation.Metric Metric}
+ * annotation is used to provide metadata for the metric being injected. If a
+ * metric with the same name exists in the
+ * {@link org.eclipse.microprofile.metrics.MetricRegistry MetricRegistry}, the
+ * metric is returned. Otherwise, a new metric is registered into the
+ * MetricRegistry along with the metadata provided by the {@literal @}Metric
+ * annotation.
+ * <p>
+ * For example,
+ * 
+ * <pre>
+ * <code>
+ *     {@literal @}Inject
+ *     {@literal @}Metric(name="histogram", description="The description")
+ *     public Histogram histogram;
+ * </code>
+ * </pre>
+ * 
+ * <h2>Interceptor Bindings</h2>
+ * <p>
+ * MicroProfile Metrics provides four interceptor bindings which can be used to
+ * instrument an application: {@literal @}Counted, {@literal @}Gauge,
+ * {@literal @}Metered, {@literal @}Timed.
+ * <p>
+ * An example using {@literal @}Counted,
+ * 
+ * <pre>
+ * <code>
+ *     {@literal @}Counted (name="visitorCount",
+ *         description="The number of visitors to the application") 
+ *     public void visit () {
+ *         ...
+ *     }
+ * </code>
+ * </pre>
+ * <p>
+ * An example using {@literal @}Gauge,
+ * 
+ * <pre>
+ * <code>
+ *     {@literal @}Gauge(name = "queueSize")
+ *     public int getQueueSize() {
+ *         return queue.size;
+ *     }
+ * </code>
+ * </pre>
+ * 
+ * 
+ * <h2>CDI Qualifier</h2>
+ * <p>
+ * The {@link org.eclipse.microprofile.metrics.annotation.RegistryType
+ * RegistryType} is used to identify which <code>MetricRegistry</code> (Application, Base, or
+ * Vendor) should be injected. By default, no <code>RegistryType</code> will
+ * inject the application <code>MetricRegistry</code>.
+ * 
+ * <pre>
+ * <code>
+ *      {@literal @}Inject
+ *      {@literal @}RegistryType(type=MetricRegistry.Type.BASE)
+ *      MetricRegistry baseRegistry;
+ * </code>
+ * </pre>
+ * 
+ */
 @org.osgi.annotation.versioning.Version("1.0")
 package org.eclipse.microprofile.metrics.annotation;
-

api/src/main/java/org/eclipse/microprofile/metrics/package-info.java

@@ -1,6 +1,6 @@
 /*
  **********************************************************************
- * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright (c) 2017, 2018 Contributors to the Eclipse Foundation
  *
  * See the NOTICES file(s) distributed with this work for additional
  * information regarding copyright ownership.
@@ -19,6 +19,103 @@
  *
  * SPDX-License-Identifier: Apache-2.0
  **********************************************************************/
+
+/**
+ * MicroProfile Metrics
+ * 
+ * <h2>Rational</h2>
+ * 
+ * <p>
+ * To ensure reliable operation of software it is necessary to monitor essential
+ * system parameters. There is already JMX as standard to expose metrics, but
+ * remote-JMX is not easy to deal with and especially does not fit well in a
+ * polyglot environment where other services are not running on the JVM. To
+ * enable monitoring in an easy fashion, the MicroProfile Metrics specification
+ * provides a standard to instrument an application with metrics and provides a
+ * simple REST endpoint for integration with monitoring services.
+ * 
+ * <h2>Adding Metrics</h2>
+ * <p>
+ * MicroProfile Metrics provides 5 different metric types that can be used to
+ * instrument an application. Developers can create an accompanying
+ * {@link org.eclipse.microprofile.metrics.Metadata Metadata} object to supply
+ * the metric's name, description, display name, tags, and units. Once the
+ * metric and the metadata are registered against the application
+ * {@link org.eclipse.microprofile.metrics.MetricRegistry MetricRegistry}, the
+ * metrics will be available in the REST endpoints.
+ * 
+ * <h2>Metric Types</h2>
+ * 
+ * <p>
+ * {@link org.eclipse.microprofile.metrics.Counter Counter} is used to measure
+ * an increasing/decreasing value.
+ * <p>
+ * Example usage:
+ * 
+ * <pre>
+ * <code>
+ *     Counter count = metricRegistry.counter(metadata);
+ *     count.inc();
+ * </code>
+ * </pre>
+ * 
+ * {@link org.eclipse.microprofile.metrics.Counter Gauge} is used to provide the
+ * immediate measurement of a value.
+ * <p>
+ * Example usage:
+ * 
+ * <pre>
+ * <code>
+ *     Gauge&lt;Double&gt; temperature = new Gauge&lt;Double&gt;() {
+ *         public Double getValue() {
+ *             return getTemperature();
+ *         }
+ *     };
+ *     metricRegistry.register(metadata, temperature);
+ * </code>
+ * </pre>
+ * 
+ * 
+ * {@link org.eclipse.microprofile.metrics.Meter Meter} is used to measure the
+ * frequency of an event.
+ * <p>
+ * Example usage:
+ * 
+ * <pre>
+ * <code>
+ *     Meter meter = metricRegistry.meter(metadata);
+ *     meter.mark();
+ * </code>
+ * </pre>
+ * 
+ * 
+ * {@link org.eclipse.microprofile.metrics.Histogram Histogram} is used to
+ * sample and compute the distribution of values
+ * <p>
+ * Example usage:
+ * 
+ * <pre>
+ * <code>
+ *     Histogram histogram = metricRegistry.histogram(metadata);
+ *     histogram.update(score);
+ * </code>
+ * </pre>
+ * 
+ * {@link org.eclipse.microprofile.metrics.Timer Timer} is used to measure the
+ * duration of an event as well as the frequency of occurrence.
+ * <p>
+ * Example usage:
+ * 
+ * <pre>
+ * <code>
+ *     Timer timer = metricRegistry.timer(metadata);
+ *     Timer.Context context = timer.time();
+ *     
+ *     ... // code that will be timed
+ *     
+ *     context.close();
+ * </code>
+ * </pre>
+ */
 @org.osgi.annotation.versioning.Version("1.0")
 package org.eclipse.microprofile.metrics;
-