Improve docs for Span and Transaction

apm-agent-api/src/main/java/co/elastic/apm/api/Span.java

@@ -1,9 +1,18 @@
 package co.elastic.apm.api;
 
+/**
+ * A span contains information about a specific code path, executed as part of a {@link Transaction}.
+ * <p>
+ * If for example a database query happens within a recorded transaction,
+ * a span representing this database query may be created.
+ * In such a case the name of the span will contain information about the query itself,
+ * and the type will hold information about the database type.
+ * </p>
+ */
 public interface Span extends AutoCloseable {
 
     /**
-     * The name of the transaction.
+     * The name of the span.
      *
      * @param name the name of the span
      */
@@ -30,7 +39,7 @@ public interface Span extends AutoCloseable {
     void end();
 
     /**
-     * An alias for {@link #end()}
+     * An alias for {@link #end()} to make a {@link Span} work in try-with-resources statements.
      */
     @Override
     void close();

apm-agent-api/src/main/java/co/elastic/apm/api/Transaction.java

@@ -1,5 +1,8 @@
 package co.elastic.apm.api;
 
+/**
+ * Data captured by an agent representing an event occurring in a monitored service
+ */
 public interface Transaction extends AutoCloseable {
 
     String TYPE_REQUEST = "request";
@@ -14,7 +17,7 @@ public interface Transaction extends AutoCloseable {
      * Transactions with the same name and type are grouped together.
      * </p>
      *
-     * @param name
+     * @param name The name of the transaction.
      */
     void setName(String name);
 
@@ -25,11 +28,23 @@ public interface Transaction extends AutoCloseable {
      * when an incoming HTTP request is detected.
      * </p>
      *
-     * @param type
+     * @param type The type of the transaction.
      */
     void setType(String type);
 
-
+    /**
+     * A flat mapping of user-defined tags with string values.
+     * <p>
+     * Note: the tags are indexed in Elasticsearch so that they are searchable and aggregatable.
+     * By all means,
+     * you should avoid that user specified data,
+     * like URL parameters,
+     * is used as a tag key as it can lead to mapping explosions.
+     * </p>
+     *
+     * @param key   The tag key.
+     * @param value The tag value.
+     */
     void addTag(String key, String value);
 
     /**
@@ -48,9 +63,9 @@ public interface Transaction extends AutoCloseable {
      * </p>
      * The provided user context is stored under context.user in Elasticsearch on both errors and transactions.
      *
-     * @param id       the user's id or <code>null</code>, if not applicable
-     * @param email    the user's email address or <code>null</code>, if not applicable
-     * @param username the user's name or <code>null</code>, if not applicable
+     * @param id       The user's id or <code>null</code>, if not applicable.
+     * @param email    The user's email address or <code>null</code>, if not applicable.
+     * @param username The user's name or <code>null</code>, if not applicable.
      */
     void setUser(String id, String email, String username);
 
@@ -60,7 +75,7 @@ public interface Transaction extends AutoCloseable {
     void end();
 
     /**
-     * An alias for {@link #end()}
+     * An alias for {@link #end()} to make a {@link Transaction} work in try-with-resources statements.
      */
     @Override
     void close();