Merge pull request #978 from sebright/javadoc-since-tags-agent

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

12 files changed, 61 insertions, 6 deletions

diff --git a/contrib/agent/src/main/java/io/opencensus/contrib/agent/AgentMain.java b/contrib/agent/src/main/java/io/opencensus/contrib/agent/AgentMain.java
index e99bac05..49c568ed 100644
--- a/contrib/agent/src/main/java/io/opencensus/contrib/agent/AgentMain.java
+++ b/contrib/agent/src/main/java/io/opencensus/contrib/agent/AgentMain.java
@@ -43,6 +43,7 @@ import net.bytebuddy.agent.builder.AgentBuilder;
  *
  * @see <a
  *     href="https://github.com/census-instrumentation/instrumentation-java/tree/master/agent">https://github.com/census-instrumentation/instrumentation-java/tree/master/agent</a>
+ * @since 0.6
  */
 public final class AgentMain {
 
@@ -58,6 +59,7 @@ public final class AgentMain {
    *     Java programming language code
    * @throws Exception if initialization of the agent fails
    * @see java.lang.instrument
+   * @since 0.6
    */
   public static void premain(String agentArgs, Instrumentation instrumentation) throws Exception {
     checkNotNull(instrumentation, "instrumentation");
diff --git a/contrib/agent/src/main/java/io/opencensus/contrib/agent/Settings.java b/contrib/agent/src/main/java/io/opencensus/contrib/agent/Settings.java
index 5a239cd8..9f3939a0 100644
--- a/contrib/agent/src/main/java/io/opencensus/contrib/agent/Settings.java
+++ b/contrib/agent/src/main/java/io/opencensus/contrib/agent/Settings.java
@@ -24,13 +24,22 @@ import com.google.common.base.Strings;
 import com.typesafe.config.Config;
 import com.typesafe.config.ConfigFactory;
 
-/** The {@code Settings} class provides access to user-configurable settings. */
+/**
+ * The {@code Settings} class provides access to user-configurable settings.
+ *
+ * @since 0.10
+ */
 public class Settings {
 
   private static final String CONFIG_ROOT = "opencensus.contrib.agent";
 
   private final Config config;
 
+  /**
+   * Creates agent settings.
+   *
+   * @since 0.10
+   */
   @VisibleForTesting
   public Settings(Config config) {
     this.config = checkNotNull(config);
@@ -57,6 +66,7 @@ public class Settings {
    *
    * @param featurePath the feature's path expression
    * @return true, if enabled, otherwise false
+   * @since 0.10
    */
   public boolean isEnabled(String featurePath) {
     checkArgument(!Strings.isNullOrEmpty(featurePath));
diff --git a/contrib/agent/src/main/java/io/opencensus/contrib/agent/bootstrap/ContextStrategy.java b/contrib/agent/src/main/java/io/opencensus/contrib/agent/bootstrap/ContextStrategy.java
index a51a9bfd..57d4efca 100644
--- a/contrib/agent/src/main/java/io/opencensus/contrib/agent/bootstrap/ContextStrategy.java
+++ b/contrib/agent/src/main/java/io/opencensus/contrib/agent/bootstrap/ContextStrategy.java
@@ -16,7 +16,11 @@
 
 package io.opencensus.contrib.agent.bootstrap;
 
-/** Strategy interface for accessing and manipulating the context. */
+/**
+ * Strategy interface for accessing and manipulating the context.
+ *
+ * @since 0.6
+ */
 public interface ContextStrategy {
 
   /**
@@ -25,6 +29,7 @@ public interface ContextStrategy {
    *
    * @param runnable a {@link Runnable} object
    * @return the wrapped {@link Runnable} object
+   * @since 0.6
    */
   Runnable wrapInCurrentContext(Runnable runnable);
 
@@ -35,6 +40,7 @@ public interface ContextStrategy {
    * method.
    *
    * @param thread a {@link Thread} object
+   * @since 0.6
    */
   void saveContextForThread(Thread thread);
 
@@ -42,6 +48,7 @@ public interface ContextStrategy {
    * Attaches the context that was previously saved for the specified thread.
    *
    * @param thread a {@link Thread} object
+   * @since 0.6
    */
   void attachContextForThread(Thread thread);
 }
diff --git a/contrib/agent/src/main/java/io/opencensus/contrib/agent/bootstrap/ContextTrampoline.java b/contrib/agent/src/main/java/io/opencensus/contrib/agent/bootstrap/ContextTrampoline.java
index 382a161d..2e737be2 100644
--- a/contrib/agent/src/main/java/io/opencensus/contrib/agent/bootstrap/ContextTrampoline.java
+++ b/contrib/agent/src/main/java/io/opencensus/contrib/agent/bootstrap/ContextTrampoline.java
@@ -30,6 +30,8 @@ package io.opencensus.contrib.agent.bootstrap;
  *
  * <p>{@code ContextTrampoline} is implemented as a static class to allow for easy and fast use from
  * instrumented bytecode. We cannot use dependency injection for the instrumented bytecode.
+ *
+ * @since 0.9
  */
 // TODO(sebright): Fix the Checker Framework warnings.
 @SuppressWarnings("nullness")
@@ -49,6 +51,7 @@ public final class ContextTrampoline {
    * of this class is called.
    *
    * @param contextStrategy the concrete strategy for accessing and manipulating the context
+   * @since 0.9
    */
   public static void setContextStrategy(ContextStrategy contextStrategy) {
     if (ContextTrampoline.contextStrategy != null) {
@@ -69,6 +72,7 @@ public final class ContextTrampoline {
    * @param runnable a {@link Runnable} object
    * @return the wrapped {@link Runnable} object
    * @see ContextStrategy#wrapInCurrentContext
+   * @since 0.9
    */
   public static Runnable wrapInCurrentContext(Runnable runnable) {
     return contextStrategy.wrapInCurrentContext(runnable);
@@ -81,6 +85,7 @@ public final class ContextTrampoline {
    * method.
    *
    * @param thread a {@link Thread} object
+   * @since 0.9
    */
   public static void saveContextForThread(Thread thread) {
     contextStrategy.saveContextForThread(thread);
@@ -90,6 +95,7 @@ public final class ContextTrampoline {
    * Attaches the context that was previously saved for the specified thread.
    *
    * @param thread a {@link Thread} object
+   * @since 0.9
    */
   public static void attachContextForThread(Thread thread) {
     contextStrategy.attachContextForThread(thread);
diff --git a/contrib/agent/src/main/java/io/opencensus/contrib/agent/bootstrap/TraceStrategy.java b/contrib/agent/src/main/java/io/opencensus/contrib/agent/bootstrap/TraceStrategy.java
index 5cfefe20..363dbbdc 100644
--- a/contrib/agent/src/main/java/io/opencensus/contrib/agent/bootstrap/TraceStrategy.java
+++ b/contrib/agent/src/main/java/io/opencensus/contrib/agent/bootstrap/TraceStrategy.java
@@ -20,7 +20,11 @@ import com.google.errorprone.annotations.MustBeClosed;
 import java.io.Closeable;
 import javax.annotation.Nullable;
 
-/** Strategy interface for creating and manipulating trace spans. */
+/**
+ * Strategy interface for creating and manipulating trace spans.
+ *
+ * @since 0.9
+ */
 public interface TraceStrategy {
 
   /**
@@ -44,6 +48,7 @@ public interface TraceStrategy {
    *     current Context
    * @see io.opencensus.trace.Tracer#spanBuilder(java.lang.String)
    * @see io.opencensus.trace.SpanBuilder#startScopedSpan()
+   * @since 0.9
    */
   @MustBeClosed
   Closeable startScopedSpan(String spanName);
@@ -54,6 +59,7 @@ public interface TraceStrategy {
    *
    * @param scope an object representing the scope
    * @param throwable an optional Throwable
+   * @since 0.9
    */
   void endScope(Closeable scope, @Nullable Throwable throwable);
 }
diff --git a/contrib/agent/src/main/java/io/opencensus/contrib/agent/bootstrap/TraceTrampoline.java b/contrib/agent/src/main/java/io/opencensus/contrib/agent/bootstrap/TraceTrampoline.java
index b4501b45..aeae2592 100644
--- a/contrib/agent/src/main/java/io/opencensus/contrib/agent/bootstrap/TraceTrampoline.java
+++ b/contrib/agent/src/main/java/io/opencensus/contrib/agent/bootstrap/TraceTrampoline.java
@@ -34,6 +34,8 @@ import javax.annotation.Nullable;
  *
  * <p>{@code TraceTrampoline} is implemented as a static class to allow for easy and fast use from
  * instrumented bytecode. We cannot use dependency injection for the instrumented bytecode.
+ *
+ * @since 0.9
  */
 // TODO(sebright): Fix the Checker Framework warnings.
 @SuppressWarnings("nullness")
@@ -53,6 +55,7 @@ public final class TraceTrampoline {
    * this class is called.
    *
    * @param traceStrategy the concrete strategy for creating and manipulating trace spans
+   * @since 0.9
    */
   public static void setTraceStrategy(TraceStrategy traceStrategy) {
     if (TraceTrampoline.traceStrategy != null) {
@@ -87,6 +90,7 @@ public final class TraceTrampoline {
    *     current Context
    * @see io.opencensus.trace.Tracer#spanBuilder(String)
    * @see io.opencensus.trace.SpanBuilder#startScopedSpan()
+   * @since 0.9
    */
   @MustBeClosed
   public static Closeable startScopedSpan(String spanName) {
@@ -99,6 +103,7 @@ public final class TraceTrampoline {
    *
    * @param scope an object representing the scope
    * @param throwable an optional Throwable
+   * @since 0.9
    */
   public static void endScope(Closeable scope, @Nullable Throwable throwable) {
     traceStrategy.endScope(scope, throwable);
diff --git a/contrib/agent/src/main/java/io/opencensus/contrib/agent/instrumentation/ContextTrampolineInitializer.java b/contrib/agent/src/main/java/io/opencensus/contrib/agent/instrumentation/ContextTrampolineInitializer.java
index 8c79869d..17a5b1d9 100644
--- a/contrib/agent/src/main/java/io/opencensus/contrib/agent/instrumentation/ContextTrampolineInitializer.java
+++ b/contrib/agent/src/main/java/io/opencensus/contrib/agent/instrumentation/ContextTrampolineInitializer.java
@@ -22,7 +22,11 @@ import io.opencensus.contrib.agent.bootstrap.ContextStrategy;
 import io.opencensus.contrib.agent.bootstrap.ContextTrampoline;
 import net.bytebuddy.agent.builder.AgentBuilder;
 
-/** Initializes the {@link ContextTrampoline} with a concrete {@link ContextStrategy}. */
+/**
+ * Initializes the {@link ContextTrampoline} with a concrete {@link ContextStrategy}.
+ *
+ * @since 0.9
+ */
 @AutoService(Instrumenter.class)
 public final class ContextTrampolineInitializer implements Instrumenter {
 
diff --git a/contrib/agent/src/main/java/io/opencensus/contrib/agent/instrumentation/ExecutorInstrumentation.java b/contrib/agent/src/main/java/io/opencensus/contrib/agent/instrumentation/ExecutorInstrumentation.java
index bc86f65b..1e1429ce 100644
--- a/contrib/agent/src/main/java/io/opencensus/contrib/agent/instrumentation/ExecutorInstrumentation.java
+++ b/contrib/agent/src/main/java/io/opencensus/contrib/agent/instrumentation/ExecutorInstrumentation.java
@@ -40,6 +40,8 @@ import net.bytebuddy.utility.JavaModule;
  * Propagates the context of the caller of {@link Executor#execute} to the submitted {@link
  * Runnable}, just like the Microsoft .Net Framework propagates the <a
  * href="https://msdn.microsoft.com/en-us/library/system.threading.executioncontext(v=vs.110).aspx">System.Threading.ExecutionContext</a>.
+ *
+ * @since 0.6
  */
 @AutoService(Instrumenter.class)
 public final class ExecutorInstrumentation implements Instrumenter {
diff --git a/contrib/agent/src/main/java/io/opencensus/contrib/agent/instrumentation/Instrumenter.java b/contrib/agent/src/main/java/io/opencensus/contrib/agent/instrumentation/Instrumenter.java
index 397a942d..5eb197ee 100644
--- a/contrib/agent/src/main/java/io/opencensus/contrib/agent/instrumentation/Instrumenter.java
+++ b/contrib/agent/src/main/java/io/opencensus/contrib/agent/instrumentation/Instrumenter.java
@@ -19,7 +19,11 @@ package io.opencensus.contrib.agent.instrumentation;
 import io.opencensus.contrib.agent.Settings;
 import net.bytebuddy.agent.builder.AgentBuilder;
 
-/** Interface for plug-ins that add bytecode instrumentation. */
+/**
+ * Interface for plug-ins that add bytecode instrumentation.
+ *
+ * @since 0.6
+ */
 public interface Instrumenter {
 
   /**
@@ -29,6 +33,7 @@ public interface Instrumenter {
    *     added
    * @param settings the configuration settings
    * @return an {@link AgentBuilder} object having the additional instrumentation
+   * @since 0.10
    */
   AgentBuilder instrument(AgentBuilder agentBuilder, Settings settings);
 }
diff --git a/contrib/agent/src/main/java/io/opencensus/contrib/agent/instrumentation/ThreadInstrumentation.java b/contrib/agent/src/main/java/io/opencensus/contrib/agent/instrumentation/ThreadInstrumentation.java
index 0dc9fa1d..b4beba8e 100644
--- a/contrib/agent/src/main/java/io/opencensus/contrib/agent/instrumentation/ThreadInstrumentation.java
+++ b/contrib/agent/src/main/java/io/opencensus/contrib/agent/instrumentation/ThreadInstrumentation.java
@@ -38,6 +38,8 @@ import net.bytebuddy.utility.JavaModule;
  * <p>NB: A similar effect could be achieved with {@link InheritableThreadLocal}, but the semantics
  * are different: {@link InheritableThreadLocal} inherits values when the thread object is
  * initialized as opposed to when {@link Thread#start()} is called.
+ *
+ * @since 0.6
  */
 @AutoService(Instrumenter.class)
 public final class ThreadInstrumentation implements Instrumenter {
diff --git a/contrib/agent/src/main/java/io/opencensus/contrib/agent/instrumentation/TraceTrampolineInitializer.java b/contrib/agent/src/main/java/io/opencensus/contrib/agent/instrumentation/TraceTrampolineInitializer.java
index 15fee24d..4a68845c 100644
--- a/contrib/agent/src/main/java/io/opencensus/contrib/agent/instrumentation/TraceTrampolineInitializer.java
+++ b/contrib/agent/src/main/java/io/opencensus/contrib/agent/instrumentation/TraceTrampolineInitializer.java
@@ -22,7 +22,11 @@ import io.opencensus.contrib.agent.bootstrap.TraceStrategy;
 import io.opencensus.contrib.agent.bootstrap.TraceTrampoline;
 import net.bytebuddy.agent.builder.AgentBuilder;
 
-/** Initializes the {@link TraceTrampoline} with a concrete {@link TraceStrategy}. */
+/**
+ * Initializes the {@link TraceTrampoline} with a concrete {@link TraceStrategy}.
+ *
+ * @since 0.9
+ */
 @AutoService(Instrumenter.class)
 public final class TraceTrampolineInitializer implements Instrumenter {
 
diff --git a/contrib/agent/src/main/java/io/opencensus/contrib/agent/instrumentation/UrlInstrumentation.java b/contrib/agent/src/main/java/io/opencensus/contrib/agent/instrumentation/UrlInstrumentation.java
index 0af8f582..336f70b1 100644
--- a/contrib/agent/src/main/java/io/opencensus/contrib/agent/instrumentation/UrlInstrumentation.java
+++ b/contrib/agent/src/main/java/io/opencensus/contrib/agent/instrumentation/UrlInstrumentation.java
@@ -36,6 +36,8 @@ import net.bytebuddy.utility.JavaModule;
  *
  * <p>TODO(stschmidt): Replace this preliminary, java.net.URL-specific implementation with a
  * generic, configurable implementation.
+ *
+ * @since 0.9
  */
 @AutoService(Instrumenter.class)
 public final class UrlInstrumentation implements Instrumenter {