Fix all javadocs warnings and errors and re-enable javadoc for api module. (#344)

6 files changed, 23 insertions, 8 deletions

diff --git a/api/build.gradle b/api/build.gradle
index 7cfb33b2..99000c2c 100644
--- a/api/build.gradle
+++ b/api/build.gradle
@@ -8,4 +8,4 @@ dependencies {
     signature "org.codehaus.mojo.signature:java16:+@signature"
 }
 
-javadoc.exclude 'io/opencensus/**'
\ No newline at end of file
+javadoc.exclude 'io/opencensus/internal/**'
\ No newline at end of file
diff --git a/api/src/main/java/io/opencensus/common/Duration.java b/api/src/main/java/io/opencensus/common/Duration.java
index c0e9f1bc..bf490c39 100644
--- a/api/src/main/java/io/opencensus/common/Duration.java
+++ b/api/src/main/java/io/opencensus/common/Duration.java
@@ -45,19 +45,32 @@ public class Duration {
     return new Duration(seconds, nanos);
   }
 
-  /** Creates a new {@link Duration} from given milliseconds. */
+  /**
+   * Creates a new {@link Duration} from given milliseconds.
+   *
+   * @param millis the duration in milliseconds.
+   * @return a new {@link Duration} from given milliseconds.
+   */
   public static Duration fromMillis(long millis) {
     long seconds = millis / NUM_MILLIS_PER_SECOND;
     int nanos = (int) (millis % NUM_MILLIS_PER_SECOND) * NUM_NANOS_PER_MILLI;
     return new Duration(seconds, nanos);
   }
 
-  /** Returns the number of seconds in the {@link Duration}. */
+  /**
+   * Returns the number of seconds in the {@link Duration}.
+   *
+   * @return the number of seconds in the {@link Duration}.
+   */
   public long getSeconds() {
     return seconds;
   }
 
-  /** Returns the number of nanoseconds in the {@link Duration}. */
+  /**
+   * Returns the number of nanoseconds in the {@link Duration}.
+   *
+   * @return the number of nanoseconds in the {@link Duration}.
+   */
   public int getNanos() {
     return nanos;
   }
diff --git a/api/src/main/java/io/opencensus/common/Function.java b/api/src/main/java/io/opencensus/common/Function.java
index 51bf845c..6105c3e6 100644
--- a/api/src/main/java/io/opencensus/common/Function.java
+++ b/api/src/main/java/io/opencensus/common/Function.java
@@ -14,12 +14,13 @@
 package io.opencensus.common;
 
 /**
- * Used to specify matching functions for use encoding tagged unions (i.e. sum types) in Java. See
- * {@link io.opencensus.stats.ViewDescriptor} for an example of it's use.
+ * Used to specify matching functions for use encoding tagged unions (i.e. sum types) in Java.
  *
  * <p>Note: This class is based on the java.util.Function class added in Java 1.8. We cannot use the
  * Function from Java 1.8 because this library is Java 1.6 compatible.
  */
+// TODO(bdrutu): Add back "See {@link io.opencensus.stats.ViewDescriptor} for an example of its
+// use."
 public interface Function<A, B> {
   B apply(A arg);
 }
diff --git a/api/src/main/java/io/opencensus/common/Timestamp.java b/api/src/main/java/io/opencensus/common/Timestamp.java
index 34c4c851..9a1dd8bb 100644
--- a/api/src/main/java/io/opencensus/common/Timestamp.java
+++ b/api/src/main/java/io/opencensus/common/Timestamp.java
@@ -37,8 +37,6 @@ public final class Timestamp {
     this.nanos = nanos;
   }
 
-  // TODO(bdrutu): Make create and fromMillis package-protected.
-
   /**
    * Creates a new timestamp from given seconds and nanoseconds.
    *
@@ -63,6 +61,7 @@ public final class Timestamp {
   /**
    * Creates a new timestamp from the given milliseconds.
    *
+   * @param millis the timestamp represented in milliseconds since epoch.
    * @return a new timestamp from the given milliseconds.
    */
   public static Timestamp fromMillis(long millis) {
diff --git a/api/src/main/java/io/opencensus/tags/TagKey.java b/api/src/main/java/io/opencensus/tags/TagKey.java
index 970ee925..efd3e6e9 100644
--- a/api/src/main/java/io/opencensus/tags/TagKey.java
+++ b/api/src/main/java/io/opencensus/tags/TagKey.java
@@ -53,6 +53,7 @@ public abstract class TagKey<TagValueT> {
    * </ol>
    *
    * @param name the name of the key.
+   * @return a {@code TagKey<String>} with the given name.
    * @throws IllegalArgumentException if the name is not valid.
    */
   public static TagKey<String> createStringKey(String name) {
diff --git a/api/src/main/java/io/opencensus/trace/SpanContext.java b/api/src/main/java/io/opencensus/trace/SpanContext.java
index 4902f15f..56a046f1 100644
--- a/api/src/main/java/io/opencensus/trace/SpanContext.java
+++ b/api/src/main/java/io/opencensus/trace/SpanContext.java
@@ -39,6 +39,7 @@ public final class SpanContext {
    * @param traceId the trace identifier of the span context.
    * @param spanId the span identifier of the span context.
    * @param traceOptions the trace options for the span context.
+   * @return a new {@code SpanContext} with the given identifiers and options.
    */
   public static SpanContext create(TraceId traceId, SpanId spanId, TraceOptions traceOptions) {
     return new SpanContext(traceId, spanId, traceOptions);