Add '@since' Javadoc tag to all tagging APIs (issue #864).

This commit also adds missing Javadocs.

15 files changed, 116 insertions, 12 deletions

diff --git a/api/src/main/java/io/opencensus/tags/InternalUtils.java b/api/src/main/java/io/opencensus/tags/InternalUtils.java
index 734fcf98..944122e1 100644
--- a/api/src/main/java/io/opencensus/tags/InternalUtils.java
+++ b/api/src/main/java/io/opencensus/tags/InternalUtils.java
@@ -18,11 +18,20 @@ package io.opencensus.tags;
 
 import java.util.Iterator;
 
-/** Internal tagging utilities. */
+/**
+ * Internal tagging utilities.
+ *
+ * @since 0.8
+ */
 @io.opencensus.common.Internal
 public final class InternalUtils {
   private InternalUtils() {}
 
+  /**
+   * Internal tag accessor.
+   *
+   * @since 0.8
+   */
   public static Iterator<Tag> getTags(TagContext tags) {
     return tags.getIterator();
   }
diff --git a/api/src/main/java/io/opencensus/tags/Tag.java b/api/src/main/java/io/opencensus/tags/Tag.java
index 90b050d5..d5415e02 100644
--- a/api/src/main/java/io/opencensus/tags/Tag.java
+++ b/api/src/main/java/io/opencensus/tags/Tag.java
@@ -19,7 +19,11 @@ package io.opencensus.tags;
 import com.google.auto.value.AutoValue;
 import javax.annotation.concurrent.Immutable;
 
-/** {@link TagKey} paired with a {@link TagValue}. */
+/**
+ * {@link TagKey} paired with a {@link TagValue}.
+ *
+ * @since 0.8
+ */
 @Immutable
 @AutoValue
 // Suppress Checker Framework warning about missing @Nullable in generated equals method.
@@ -35,6 +39,7 @@ public abstract class Tag {
    * @param key the tag key.
    * @param value the tag value.
    * @return a {@code Tag} with the given key and value.
+   * @since 0.8
    */
   public static Tag create(TagKey key, TagValue value) {
     return new AutoValue_Tag(key, value);
@@ -44,6 +49,7 @@ public abstract class Tag {
    * Returns the tag's key.
    *
    * @return the tag's key.
+   * @since 0.8
    */
   public abstract TagKey getKey();
 
@@ -51,6 +57,7 @@ public abstract class Tag {
    * Returns the tag's value.
    *
    * @return the tag's value.
+   * @since 0.8
    */
   public abstract TagValue getValue();
 }
diff --git a/api/src/main/java/io/opencensus/tags/TagContext.java b/api/src/main/java/io/opencensus/tags/TagContext.java
index bc2a1630..841c8ab5 100644
--- a/api/src/main/java/io/opencensus/tags/TagContext.java
+++ b/api/src/main/java/io/opencensus/tags/TagContext.java
@@ -30,6 +30,8 @@ import javax.annotation.concurrent.Immutable;
  *
  * <p>For example, {@code TagContext}s can be used to label stats, log messages, or debugging
  * information.
+ *
+ * @since 0.8
  */
 @Immutable
 public abstract class TagContext {
@@ -38,6 +40,7 @@ public abstract class TagContext {
    * Returns an iterator over the tags in this {@code TagContext}.
    *
    * @return an iterator over the tags in this {@code TagContext}.
+   * @since 0.8
    */
   // This method is protected to prevent client code from accessing the tags of any TagContext. We
   // don't currently support efficient access to tags. However, every TagContext subclass needs to
diff --git a/api/src/main/java/io/opencensus/tags/TagContextBuilder.java b/api/src/main/java/io/opencensus/tags/TagContextBuilder.java
index c6c858c6..f4268968 100644
--- a/api/src/main/java/io/opencensus/tags/TagContextBuilder.java
+++ b/api/src/main/java/io/opencensus/tags/TagContextBuilder.java
@@ -18,7 +18,11 @@ package io.opencensus.tags;
 
 import io.opencensus.common.Scope;
 
-/** Builder for the {@link TagContext} class. */
+/**
+ * Builder for the {@link TagContext} class.
+ *
+ * @since 0.8
+ */
 public abstract class TagContextBuilder {
 
   /**
@@ -27,6 +31,7 @@ public abstract class TagContextBuilder {
    * @param key the {@code TagKey} which will be set.
    * @param value the {@code TagValue} to set for the given key.
    * @return this
+   * @since 0.8
    */
   public abstract TagContextBuilder put(TagKey key, TagValue value);
 
@@ -35,6 +40,7 @@ public abstract class TagContextBuilder {
    *
    * @param key the {@code TagKey} which will be removed.
    * @return this
+   * @since 0.8
    */
   public abstract TagContextBuilder remove(TagKey key);
 
@@ -42,6 +48,7 @@ public abstract class TagContextBuilder {
    * Creates a {@code TagContext} from this builder.
    *
    * @return a {@code TagContext} with the same tags as this builder.
+   * @since 0.8
    */
   public abstract TagContext build();
 
@@ -52,6 +59,7 @@ public abstract class TagContextBuilder {
    *
    * @return an object that defines a scope where the {@code TagContext} created from this builder
    *     is set to the current context.
+   * @since 0.8
    */
   public abstract Scope buildScoped();
 }
diff --git a/api/src/main/java/io/opencensus/tags/TagKey.java b/api/src/main/java/io/opencensus/tags/TagKey.java
index a6eb802f..bad2fec3 100644
--- a/api/src/main/java/io/opencensus/tags/TagKey.java
+++ b/api/src/main/java/io/opencensus/tags/TagKey.java
@@ -30,6 +30,8 @@ import javax.annotation.concurrent.Immutable;
  *
  * <p>{@code TagKey}s are designed to be used as constants. Declaring each key as a constant
  * prevents key names from being validated multiple times.
+ *
+ * @since 0.8
  */
 @Immutable
 @AutoValue
@@ -37,7 +39,11 @@ import javax.annotation.concurrent.Immutable;
 @AutoValue.CopyAnnotations
 @SuppressWarnings("nullness")
 public abstract class TagKey {
-  /** The maximum length for a tag key name. The value is {@value #MAX_LENGTH}. */
+  /**
+   * The maximum length for a tag key name. The value is {@value #MAX_LENGTH}.
+   *
+   * @since 0.8
+   */
   public static final int MAX_LENGTH = 255;
 
   TagKey() {}
@@ -55,6 +61,7 @@ public abstract class TagKey {
    * @param name the name of the key.
    * @return a {@code TagKey} with the given name.
    * @throws IllegalArgumentException if the name is not valid.
+   * @since 0.8
    */
   public static TagKey create(String name) {
     checkArgument(isValid(name));
@@ -65,6 +72,7 @@ public abstract class TagKey {
    * Returns the name of the key.
    *
    * @return the name of the key.
+   * @since 0.8
    */
   public abstract String getName();
 
diff --git a/api/src/main/java/io/opencensus/tags/TagValue.java b/api/src/main/java/io/opencensus/tags/TagValue.java
index bd2894a7..07ccc2cc 100644
--- a/api/src/main/java/io/opencensus/tags/TagValue.java
+++ b/api/src/main/java/io/opencensus/tags/TagValue.java
@@ -26,6 +26,8 @@ import javax.annotation.concurrent.Immutable;
  *
  * <p>Validation ensures that the {@code String} has a maximum length of {@link #MAX_LENGTH} and
  * contains only printable ASCII characters.
+ *
+ * @since 0.8
  */
 @Immutable
 @AutoValue
@@ -33,7 +35,11 @@ import javax.annotation.concurrent.Immutable;
 @AutoValue.CopyAnnotations
 @SuppressWarnings("nullness")
 public abstract class TagValue {
-  /** The maximum length for a tag value. The value is {@value #MAX_LENGTH}. */
+  /**
+   * The maximum length for a tag value. The value is {@value #MAX_LENGTH}.
+   *
+   * @since 0.8
+   */
   public static final int MAX_LENGTH = 255;
 
   TagValue() {}
@@ -49,6 +55,7 @@ public abstract class TagValue {
    *
    * @param value the tag value.
    * @throws IllegalArgumentException if the {@code String} is not valid.
+   * @since 0.8
    */
   public static TagValue create(String value) {
     Preconditions.checkArgument(isValid(value));
@@ -59,6 +66,7 @@ public abstract class TagValue {
    * Returns the tag value as a {@code String}.
    *
    * @return the tag value as a {@code String}.
+   * @since 0.8
    */
   public abstract String asString();
 
diff --git a/api/src/main/java/io/opencensus/tags/Tagger.java b/api/src/main/java/io/opencensus/tags/Tagger.java
index 1d786f71..f3ba0f5b 100644
--- a/api/src/main/java/io/opencensus/tags/Tagger.java
+++ b/api/src/main/java/io/opencensus/tags/Tagger.java
@@ -27,6 +27,8 @@ import io.opencensus.common.Scope;
  * <p>Implementations may have different constraints and are free to convert tag contexts to their
  * own subtypes. This means callers cannot assume the {@link #getCurrentTagContext() current
  * context} is the same instance as the one {@link #withTagContext(TagContext) placed into scope}.
+ *
+ * @since 0.8
  */
 public abstract class Tagger {
 
@@ -34,6 +36,7 @@ public abstract class Tagger {
    * Returns an empty {@code TagContext}.
    *
    * @return an empty {@code TagContext}.
+   * @since 0.8
    */
   public abstract TagContext empty();
 
@@ -41,6 +44,7 @@ public abstract class Tagger {
    * Returns the current {@code TagContext}.
    *
    * @return the current {@code TagContext}.
+   * @since 0.8
    */
   public abstract TagContext getCurrentTagContext();
 
@@ -48,6 +52,7 @@ public abstract class Tagger {
    * Returns a new empty {@code Builder}.
    *
    * @return a new empty {@code Builder}.
+   * @since 0.8
    */
   public abstract TagContextBuilder emptyBuilder();
 
@@ -55,6 +60,7 @@ public abstract class Tagger {
    * Returns a builder based on this {@code TagContext}.
    *
    * @return a builder based on this {@code TagContext}.
+   * @since 0.8
    */
   public abstract TagContextBuilder toBuilder(TagContext tags);
 
@@ -62,6 +68,7 @@ public abstract class Tagger {
    * Returns a new builder created from the current {@code TagContext}.
    *
    * @return a new builder created from the current {@code TagContext}.
+   * @since 0.8
    */
   public abstract TagContextBuilder currentBuilder();
 
@@ -73,6 +80,7 @@ public abstract class Tagger {
    * @param tags the {@code TagContext} to be set to the current context.
    * @return an object that defines a scope where the given {@code TagContext} is set to the current
    *     context.
+   * @since 0.8
    */
   public abstract Scope withTagContext(TagContext tags);
 }
diff --git a/api/src/main/java/io/opencensus/tags/TaggingState.java b/api/src/main/java/io/opencensus/tags/TaggingState.java
index 861aca74..88970361 100644
--- a/api/src/main/java/io/opencensus/tags/TaggingState.java
+++ b/api/src/main/java/io/opencensus/tags/TaggingState.java
@@ -16,7 +16,11 @@
 
 package io.opencensus.tags;
 
-/** State of the {@link TagsComponent}. */
+/**
+ * State of the {@link TagsComponent}.
+ *
+ * @since 0.8
+ */
 public enum TaggingState {
   // TODO(sebright): Should we add a state that propagates the tags, but doesn't allow
   // modifications?
@@ -26,6 +30,8 @@ public enum TaggingState {
    *
    * <p>The {@link TagsComponent} can add tags to {@link TagContext}s, propagate {@code TagContext}s
    * in the current context, and serialize {@code TagContext}s.
+   *
+   * @since 0.8
    */
   ENABLED,
 
@@ -34,6 +40,8 @@ public enum TaggingState {
    *
    * <p>The {@link TagsComponent} may not add tags to {@link TagContext}s, propagate {@code
    * TagContext}s in the current context, or serialize {@code TagContext}s.
+   *
+   * @since 0.8
    */
   // TODO(sebright): Document how this interacts with stats collection.
   DISABLED
diff --git a/api/src/main/java/io/opencensus/tags/Tags.java b/api/src/main/java/io/opencensus/tags/Tags.java
index 5832ca5d..b784b5f5 100644
--- a/api/src/main/java/io/opencensus/tags/Tags.java
+++ b/api/src/main/java/io/opencensus/tags/Tags.java
@@ -23,7 +23,11 @@ import java.util.logging.Level;
 import java.util.logging.Logger;
 import javax.annotation.Nullable;
 
-/** Class for accessing the default {@link TagsComponent}. */
+/**
+ * Class for accessing the default {@link TagsComponent}.
+ *
+ * @since 0.8
+ */
 public final class Tags {
   private static final Logger logger = Logger.getLogger(Tags.class.getName());
 
@@ -36,6 +40,7 @@ public final class Tags {
    * Returns the default {@code Tagger}.
    *
    * @return the default {@code Tagger}.
+   * @since 0.8
    */
   public static Tagger getTagger() {
     return tagsComponent.getTagger();
@@ -45,6 +50,7 @@ public final class Tags {
    * Returns the default {@code TagPropagationComponent}.
    *
    * @return the default {@code TagPropagationComponent}.
+   * @since 0.8
    */
   public static TagPropagationComponent getTagPropagationComponent() {
     return tagsComponent.getTagPropagationComponent();
@@ -60,6 +66,7 @@ public final class Tags {
    * throw an {@code IllegalStateException}.
    *
    * @return the current {@code TaggingState}.
+   * @since 0.8
    */
   public static TaggingState getState() {
     return tagsComponent.getState();
@@ -76,6 +83,7 @@ public final class Tags {
    *     #getState()}, use a stale value, and behave incorrectly. It is only safe to call early in
    *     initialization. This method throws {@link IllegalStateException} after {@link #getState()}
    *     has been called, in order to limit changes to the result of {@code getState()}.
+   * @since 0.8
    */
   @Deprecated
   public static void setState(TaggingState state) {
diff --git a/api/src/main/java/io/opencensus/tags/TagsComponent.java b/api/src/main/java/io/opencensus/tags/TagsComponent.java
index b0965077..d34f1951 100644
--- a/api/src/main/java/io/opencensus/tags/TagsComponent.java
+++ b/api/src/main/java/io/opencensus/tags/TagsComponent.java
@@ -22,13 +22,23 @@ import io.opencensus.tags.propagation.TagPropagationComponent;
  * Class that holds the implementation for {@link Tagger} and {@link TagPropagationComponent}.
  *
  * <p>All objects returned by methods on {@code TagsComponent} are cacheable.
+ *
+ * @since 0.8
  */
 public abstract class TagsComponent {
 
-  /** Returns the {@link Tagger} for this implementation. */
+  /**
+   * Returns the {@link Tagger} for this implementation.
+   *
+   * @since 0.8
+   */
   public abstract Tagger getTagger();
 
-  /** Returns the {@link TagPropagationComponent} for this implementation. */
+  /**
+   * Returns the {@link TagPropagationComponent} for this implementation.
+   *
+   * @since 0.8
+   */
   public abstract TagPropagationComponent getTagPropagationComponent();
 
   /**
@@ -41,6 +51,7 @@ public abstract class TagsComponent {
    * throw an {@code IllegalStateException}.
    *
    * @return the current {@code TaggingState}.
+   * @since 0.8
    */
   public abstract TaggingState getState();
 
@@ -55,6 +66,7 @@ public abstract class TagsComponent {
    *     #getState()}, use a stale value, and behave incorrectly. It is only safe to call early in
    *     initialization. This method throws {@link IllegalStateException} after {@code getState()}
    *     has been called, in order to limit changes to the result of {@code getState()}.
+   * @since 0.8
    */
   @Deprecated
   public abstract void setState(TaggingState state);
diff --git a/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java b/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java
index f89d7b0d..39eb8cee 100644
--- a/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java
+++ b/api/src/main/java/io/opencensus/tags/propagation/TagContextBinarySerializer.java
@@ -24,6 +24,8 @@ import io.opencensus.tags.TagContext;
  * <p>See <a
  * href="https://github.com/census-instrumentation/opencensus-specs/blob/master/encodings/BinaryEncoding.md#tag-context">opencensus-specs</a>
  * for the specification of the cross-language binary serialization format.
+ *
+ * @since 0.8
  */
 public abstract class TagContextBinarySerializer {
 
@@ -36,6 +38,7 @@ public abstract class TagContextBinarySerializer {
    * @return the on-the-wire representation of a {@code TagContext}.
    * @throws TagContextSerializationException if the result would be larger than the maximum allowed
    *     serialized size.
+   * @since 0.8
    */
   public abstract byte[] toByteArray(TagContext tags) throws TagContextSerializationException;
 
@@ -48,6 +51,7 @@ public abstract class TagContextBinarySerializer {
    * @return a {@code TagContext} deserialized from {@code bytes}.
    * @throws TagContextDeserializationException if there is a parse error, the input contains
    *     invalid tags, or the input is larger than the maximum allowed serialized size.
+   * @since 0.8
    */
   public abstract TagContext fromByteArray(byte[] bytes) throws TagContextDeserializationException;
 }
diff --git a/api/src/main/java/io/opencensus/tags/propagation/TagContextDeserializationException.java b/api/src/main/java/io/opencensus/tags/propagation/TagContextDeserializationException.java
index eb8d18ea..11dcb59f 100644
--- a/api/src/main/java/io/opencensus/tags/propagation/TagContextDeserializationException.java
+++ b/api/src/main/java/io/opencensus/tags/propagation/TagContextDeserializationException.java
@@ -18,7 +18,11 @@ package io.opencensus.tags.propagation;
 
 import io.opencensus.tags.TagContext;
 
-/** Exception thrown when a {@link TagContext} cannot be parsed. */
+/**
+ * Exception thrown when a {@link TagContext} cannot be parsed.
+ *
+ * @since 0.8
+ */
 public final class TagContextDeserializationException extends Exception {
   private static final long serialVersionUID = 0L;
 
@@ -26,6 +30,7 @@ public final class TagContextDeserializationException extends Exception {
    * Constructs a new {@code TagContextParseException} with the given message.
    *
    * @param message a message describing the error.
+   * @since 0.8
    */
   public TagContextDeserializationException(String message) {
     super(message);
@@ -36,6 +41,7 @@ public final class TagContextDeserializationException extends Exception {
    *
    * @param message a message describing the error.
    * @param cause the cause of the error.
+   * @since 0.8
    */
   public TagContextDeserializationException(String message, Throwable cause) {
     super(message, cause);
diff --git a/api/src/main/java/io/opencensus/tags/propagation/TagContextSerializationException.java b/api/src/main/java/io/opencensus/tags/propagation/TagContextSerializationException.java
index b702dd74..bb3c9b74 100644
--- a/api/src/main/java/io/opencensus/tags/propagation/TagContextSerializationException.java
+++ b/api/src/main/java/io/opencensus/tags/propagation/TagContextSerializationException.java
@@ -18,7 +18,11 @@ package io.opencensus.tags.propagation;
 
 import io.opencensus.tags.TagContext;
 
-/** Exception thrown when a {@link TagContext} cannot be serialized. */
+/**
+ * Exception thrown when a {@link TagContext} cannot be serialized.
+ *
+ * @since 0.8
+ */
 public final class TagContextSerializationException extends Exception {
   private static final long serialVersionUID = 0L;
 
@@ -26,6 +30,7 @@ public final class TagContextSerializationException extends Exception {
    * Constructs a new {@code TagContextSerializationException} with the given message.
    *
    * @param message a message describing the error.
+   * @since 0.8
    */
   public TagContextSerializationException(String message) {
     super(message);
@@ -36,6 +41,7 @@ public final class TagContextSerializationException extends Exception {
    *
    * @param message a message describing the error.
    * @param cause the cause of the error.
+   * @since 0.8
    */
   public TagContextSerializationException(String message, Throwable cause) {
     super(message, cause);
diff --git a/api/src/main/java/io/opencensus/tags/propagation/TagPropagationComponent.java b/api/src/main/java/io/opencensus/tags/propagation/TagPropagationComponent.java
index c51a845c..6ececa79 100644
--- a/api/src/main/java/io/opencensus/tags/propagation/TagPropagationComponent.java
+++ b/api/src/main/java/io/opencensus/tags/propagation/TagPropagationComponent.java
@@ -18,7 +18,11 @@ package io.opencensus.tags.propagation;
 
 import io.opencensus.tags.TagContext;
 
-/** Object containing all supported {@link TagContext} propagation formats. */
+/**
+ * Object containing all supported {@link TagContext} propagation formats.
+ *
+ * @since 0.8
+ */
 // TODO(sebright): Add an HTTP serializer.
 public abstract class TagPropagationComponent {
 
@@ -26,6 +30,7 @@ public abstract class TagPropagationComponent {
    * Returns the {@link TagContextBinarySerializer} for this implementation.
    *
    * @return the {@code TagContextBinarySerializer} for this implementation.
+   * @since 0.8
    */
   public abstract TagContextBinarySerializer getBinarySerializer();
 }
diff --git a/api/src/main/java/io/opencensus/tags/unsafe/ContextUtils.java b/api/src/main/java/io/opencensus/tags/unsafe/ContextUtils.java
index 2baf1a2a..8936bbbb 100644
--- a/api/src/main/java/io/opencensus/tags/unsafe/ContextUtils.java
+++ b/api/src/main/java/io/opencensus/tags/unsafe/ContextUtils.java
@@ -28,6 +28,8 @@ import javax.annotation.concurrent.Immutable;
  *
  * <p>Most code should interact with the current context via the public APIs in {@link
  * io.opencensus.tags.TagContext} and avoid accessing {@link #TAG_CONTEXT_KEY} directly.
+ *
+ * @since 0.8
  */
 public final class ContextUtils {
   private static final TagContext EMPTY_TAG_CONTEXT = new EmptyTagContext();
@@ -37,6 +39,8 @@ public final class ContextUtils {
   /**
    * The {@link io.grpc.Context.Key} used to interact with the {@code TagContext} contained in the
    * {@link io.grpc.Context}.
+   *
+   * @since 0.8
    */
   public static final Context.Key<TagContext> TAG_CONTEXT_KEY =
       Context.keyWithDefault("opencensus-tag-context-key", EMPTY_TAG_CONTEXT);