Add Javadocs

Also a minor fix to the phrasing in `MarvelLicensee#expirationMessages()`.

Original commit: elastic/x-pack-elasticsearch@9366c07930

elasticsearch/x-pack/marvel/src/main/java/org/elasticsearch/marvel/agent/AgentService.java

@@ -29,6 +29,15 @@ import java.util.Locale;
 import java.util.Set;
 import java.util.concurrent.TimeUnit;
 
+/**
+ * The {@code AgentService} is a service that does the work of publishing the details to the monitoring cluster.
+ * <p>
+ * If this service is stopped, then the attached, monitored node is not going to publish its details to the monitoring cluster. Given
+ * service life cycles, the intended way to temporarily stop the publishing is using the start and stop collection methods.
+ *
+ * @see #stopCollection()
+ * @see #startCollection()
+ */
 public class AgentService extends AbstractLifecycleComponent<AgentService> {
 
     private volatile ExportingWorker exportingWorker;

elasticsearch/x-pack/marvel/src/main/java/org/elasticsearch/marvel/agent/renderer/Renderer.java

@@ -11,9 +11,22 @@ import java.io.IOException;
 import java.io.OutputStream;
 
 /**
- * Renderers are used to render documents using a given OutputStream.
+ * {@code Renderer}s are used to render documents using a given OutputStream.
+ * <p>
+ * Each {@code Renderer} can be thought of as a generator of a unique document <em>type</em> within the resulting ES index. For example,
+ * there will be details about shards, which requires a unique document type and there will also be details about indices, which requires
+ * their own unique documents.
+ *
+ * @see AbstractRenderer
  */
 public interface Renderer<T> {
-
+    /**
+     * Convert the given {@code document} type into something that can be sent to the monitoring cluster.
+     *
+     * @param document The arbitrary document (e.g., details about a shard)
+     * @param xContentType The rendered content type (e.g., JSON)
+     * @param os The buffer
+     * @throws IOException if any unexpected error occurs
+     */
     void render(T document, XContentType xContentType, OutputStream os) throws IOException;
 }

elasticsearch/x-pack/marvel/src/main/java/org/elasticsearch/marvel/license/MarvelLicensee.java

@@ -16,7 +16,15 @@ import org.elasticsearch.license.plugin.core.Licensee;
 import org.elasticsearch.license.plugin.core.LicenseeRegistry;
 import org.elasticsearch.marvel.Marvel;
 
-
+/**
+ * {@code MarvelLicensee} determines whether certain features of Monitoring are enabled or disabled.
+ * <p>
+ * Once the license expires, the agent will stop:
+ * <ul>
+ * <li>Collecting and publishing new metrics.</li>
+ * <li>Cleaning up (deleting) older indices.</li>
+ * </ul>
+ */
 public class MarvelLicensee extends AbstractLicenseeComponent<MarvelLicensee> implements Licensee {
 
     @Inject
@@ -24,11 +32,17 @@ public class MarvelLicensee extends AbstractLicenseeComponent<MarvelLicensee> im
         super(settings, Marvel.NAME, clientService);
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @see #collectionEnabled()
+     * @see #cleaningEnabled()
+     */
     @Override
     public String[] expirationMessages() {
         return new String[] {
                 "The agent will stop collecting cluster and indices metrics",
-                "The agent will stop to automatically clean up indices older than [xpack.monitoring.history.duration]",
+                "The agent will stop automatically cleaning indices older than [xpack.monitoring.history.duration]",
         };
     }
 
@@ -58,21 +72,47 @@ public class MarvelLicensee extends AbstractLicenseeComponent<MarvelLicensee> im
         return Strings.EMPTY_ARRAY;
     }
 
+    /**
+     * Determine if the index cleaning service is enabled.
+     * <p>
+     * Collection is only disabled <em>automatically</em> when the license expires/becomes invalid. Collection <em>can</em> be disabled
+     * explicitly by the user, although that's generally a temporary solution to unrelated issues (e.g., initial setup when the monitoring
+     * cluster doesn't actually exist).
+     *
+     * @return {@code true} as long as the license is valid. Otherwise {@code false}.
+     */
     public boolean collectionEnabled() {
-        // when checking multiple parts of the status, we should get a local reference to the status object since it is
-        // volatile and can change between check statements...
+        // note: status is volatile, so don't do multiple checks without a local ref
         Status status = this.status;
-        return status.getMode() != License.OperationMode.NONE &&
-                status.getLicenseState() != LicenseState.DISABLED;
+        return status.getMode() != License.OperationMode.NONE && status.getLicenseState() != LicenseState.DISABLED;
     }
 
+    /**
+     * Determine if the index cleaning service is enabled.
+     * <p>
+     * Index cleaning is only disabled when the license expires/becomes invalid.
+     *
+     * @return {@code true} as long as the license is valid. Otherwise {@code false}.
+     */
     public boolean cleaningEnabled() {
+        // note: status is volatile, so don't do multiple checks without a local ref
         Status status = this.status;
-        return status.getMode() != License.OperationMode.NONE &&
-                status.getLicenseState() != LicenseState.DISABLED;
+        return status.getMode() != License.OperationMode.NONE && status.getLicenseState() != LicenseState.DISABLED;
     }
 
+    /**
+     * Determine if the current license allows the retention of indices to be modified.
+     * <p>
+     * Only users with the following license types can update the retention period:
+     * <ul>
+     * <li>{@link License.OperationMode#PLATINUM}</li>
+     * <li>{@link License.OperationMode#GOLD}</li>
+     * </ul>
+     *
+     * @return {@code true} if the user is allowed to modify the retention. Otherwise {@code false}.
+     */
     public boolean allowUpdateRetention() {
+        // note: status is volatile, so don't do multiple checks without a local ref
         Status status = this.status;
         return status.getMode() == License.OperationMode.PLATINUM || status.getMode() == License.OperationMode.GOLD;
     }