fix: Add Documentation (#221)

* fix: Add javadoc to public classes. * fix: Reformat. * fix: Suggested docs changes. * fix: Fix mvn site issues.
googleapis · Aug 25, 2020 · 6c430da · 6c430da
1 parent f25077d
commit 6c430da
Show file tree

Hide file tree

Showing 35 changed files with 237 additions and 31 deletions.
diff --git a/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/AdminClientSettings.java b/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/AdminClientSettings.java
@@ -24,15 +24,24 @@
 import io.grpc.StatusException;
 import java.util.Optional;
 
+/** Settings for construction a Pub/Sub Lite AdminClient. */
 @AutoValue
 public abstract class AdminClientSettings {
 
   // Required parameters.
+
+  /**
+   * The <a href="https://cloud.google.com/pubsub/lite/docs/locations">cloud region</a> to perform
+   * admin operations for.
+   */
   abstract CloudRegion region();
 
   // Optional parameters.
+
+  /** The retry settings for this client. */
   abstract RetrySettings retrySettings();
 
+  /** A stub to use to connect. */
   abstract Optional<AdminServiceBlockingStub> stub();
 
   public static Builder newBuilder() {
@@ -43,13 +52,19 @@ public static Builder newBuilder() {
   @AutoValue.Builder
   public abstract static class Builder {
     // Required parameters.
+
+    /** The cloud region to perform admin operations for. */
     public abstract Builder setRegion(CloudRegion region);
 
     // Optional parameters.
+
+    /** The retry settings for this client. */
     public abstract Builder setRetrySettings(RetrySettings retrySettings);
 
+    /** A stub to use to connect. */
     public abstract Builder setStub(AdminServiceBlockingStub stub);
 
+    /** Build the settings object. */
     public abstract AdminClientSettings build();
   }
 

diff --git a/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/CloudRegion.java b/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/CloudRegion.java
@@ -19,13 +19,16 @@
 import com.google.auto.value.AutoValue;
 import java.io.Serializable;
 
+/** A wrapped string representing a Google Cloud region. */
 @AutoValue
 public abstract class CloudRegion implements Serializable {
   private static final long serialVersionUID = 6814654654L;
 
+  /** Construct a CloudRegion from a string. */
   public static CloudRegion of(String value) {
     return new AutoValue_CloudRegion(value);
   }
 
+  /** The string representing this region. */
   public abstract String value();
 }
diff --git a/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/CloudZone.java b/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/CloudZone.java
@@ -21,6 +21,7 @@
 import io.grpc.StatusException;
 import java.io.Serializable;
 
+/** A representation of a Google Cloud zone. */
 @AutoValue
 public abstract class CloudZone implements Serializable {
   private static final long serialVersionUID = 867184651465L;
@@ -29,8 +30,10 @@ public static CloudZone of(CloudRegion region, char zoneId) {
     return new AutoValue_CloudZone(region, zoneId);
   }
 
-  // Construct a CloudZone from a valid zone string. `zone` must be formatted as:
-  // <location>-<direction><number>-<letter>
+  /**
+   * Construct a CloudZone from a valid zone string. `zone` must be formatted as:
+   * &lt;location&gt;-&lt;direction&gt;&lt;number&gt;-&lt;letter&gt;
+   */
   public static CloudZone parse(String zone) throws StatusException {
     String[] splits = zone.split("-", -1);
     if (splits.length != 3) {
@@ -43,10 +46,13 @@ public static CloudZone parse(String zone) throws StatusException {
     return of(region, splits[2].charAt(0));
   }
 
+  /** The region this zone is in. */
   public abstract CloudRegion region();
 
+  /** The character identifier for this zone in this region. */
   public abstract char zoneId();
 
+  /** {@inheritDoc} */
   @Override
   public final String toString() {
     return String.format("%s-%c", region().value(), zoneId());

diff --git a/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/Constants.java b/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/Constants.java
@@ -19,6 +19,7 @@
 import com.google.api.gax.retrying.RetrySettings;
 import org.threeten.bp.Duration;
 
+/** Useful general constants for Pub/Sub Lite. */
 public class Constants {
   public static final RetrySettings DEFAULT_RETRY_SETTINGS =
       RetrySettings.newBuilder()

diff --git a/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/Endpoints.java b/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/Endpoints.java
@@ -16,7 +16,9 @@
 
 package com.google.cloud.pubsublite;
 
+/** Constructs regional endpoints from a CloudRegion. */
 public final class Endpoints {
+  /** Construct a regional endpoint from a CloudRegion. */
   public static String regionalEndpoint(CloudRegion region) {
     return region.value() + "-pubsublite.googleapis.com";
   }

diff --git a/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/ErrorCodes.java b/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/ErrorCodes.java
@@ -19,6 +19,7 @@
 import com.google.common.collect.ImmutableSet;
 import io.grpc.Status.Code;
 
+/** Pub/Sub Lite retryable error codes. */
 public final class ErrorCodes {
   public static final ImmutableSet<Code> RETRYABLE_CODES =
       ImmutableSet.of(

diff --git a/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/LocationPath.java b/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/LocationPath.java
@@ -21,10 +21,17 @@
 import com.google.auto.value.AutoValue;
 import java.io.Serializable;
 
+/**
+ * A string wrapper representing a project and location. Should be structured like:
+ *
+ * <p>projects/&lt;project number&gt;/locations/&lt;cloud zone&gt;
+ */
 @AutoValue
 public abstract class LocationPath implements Serializable {
+  /** The string value of this location path. */
   public abstract String value();
 
+  /** Construct a LocationPath from its string value. */
   public static LocationPath of(String value) {
     checkArgument(!value.isEmpty());
     return new AutoValue_LocationPath(value);

diff --git a/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/LocationPaths.java b/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/LocationPaths.java
@@ -22,24 +22,29 @@
 import com.google.auto.value.AutoValue;
 import io.grpc.StatusException;
 
+/** Helpers for constructing valid LocationPaths. */
 @AutoValue
 public abstract class LocationPaths {
   abstract ProjectNumber projectNumber();
 
   abstract CloudZone zone();
 
+  /** Create a new LocationPath builder. */
   public static Builder newBuilder() {
     return new AutoValue_LocationPaths.Builder();
   }
 
   @AutoValue.Builder
   public abstract static class Builder {
+    /** The project number. */
     public abstract Builder setProjectNumber(ProjectNumber number);
 
+    /** The Google Cloud zone. */
     public abstract Builder setZone(CloudZone zone);
 
     abstract LocationPaths autoBuild();
 
+    /** Build a new LocationPath. */
     public LocationPath build() {
       LocationPaths built = autoBuild();
       return LocationPath.of(
@@ -53,11 +58,13 @@ private static void checkSplits(String[] splits) throws StatusException {
     checkArgument(splits[2].equals("locations"));
   }
 
+  /** Check that the provided LocationPath is valid. */
   public static void check(LocationPath path) throws StatusException {
     ProjectNumber unusedProjectNumber = getProjectNumber(path);
     CloudZone unusedZone = getZone(path);
   }
 
+  /** Get the ProjectNumber from a LocationPath. */
   public static ProjectNumber getProjectNumber(LocationPath path) throws StatusException {
     String[] splits = path.value().split("/");
     checkSplits(splits);
@@ -68,6 +75,7 @@ public static ProjectNumber getProjectNumber(LocationPath path) throws StatusExc
     }
   }
 
+  /** Get the CloudZone from a LocationPath. */
   public static CloudZone getZone(LocationPath path) throws StatusException {
     String[] splits = path.value().split("/");
     checkSplits(splits);

diff --git a/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/Message.java b/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/Message.java
@@ -27,23 +27,30 @@
 /** A user message. */
 @AutoValue
 public abstract class Message {
+  /** The key for this message. All messages with the same key are routed to the same partition. */
   public abstract ByteString key();
 
+  /** The data payload for this message. */
   public abstract ByteString data();
 
+  /** A multimap of attributes for this message. */
   public abstract ImmutableListMultimap<String, ByteString> attributes();
 
+  /** The user-provided event time for this message. */
   public abstract Optional<Timestamp> eventTime();
 
+  /** Get a new builder for a message. */
   public static Builder builder() {
     return new AutoValue_Message.Builder()
         .setKey(ByteString.EMPTY)
         .setData(ByteString.EMPTY)
         .setAttributes(ImmutableListMultimap.of());
   }
 
+  /** Convert an existing message to a builder. */
   public abstract Builder toBuilder();
 
+  /** Convert this to a message proto. */
   public PubSubMessage toProto() {
     PubSubMessage.Builder builder = PubSubMessage.newBuilder();
     builder.setKey(key());
@@ -60,6 +67,7 @@ public PubSubMessage toProto() {
     return builder.build();
   }
 
+  /** Construct a message from a proto. */
   public static Message fromProto(PubSubMessage proto) {
     Message.Builder builder = Message.builder().setKey(proto.getKey()).setData(proto.getData());
     if (proto.hasEventTime()) {
@@ -77,14 +85,21 @@ public static Message fromProto(PubSubMessage proto) {
 
   @AutoValue.Builder
   public abstract static class Builder {
+    /**
+     * The key for this message. All messages with the same key are routed to the same partition.
+     */
     public abstract Builder setKey(ByteString key);
 
+    /** The data payload for this message. */
     public abstract Builder setData(ByteString data);
 
+    /** A multimap of attributes for this message. */
     public abstract Builder setAttributes(ImmutableListMultimap<String, ByteString> attributes);
 
+    /** The user provided event time for this message. */
     public abstract Builder setEventTime(Timestamp eventTime);
 
+    /** Build a message. */
     public abstract Message build();
   }
 }
diff --git a/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/MessageTransformer.java b/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/MessageTransformer.java
@@ -18,8 +18,11 @@
 
 import io.grpc.StatusException;
 
-// A MessageTransformer details how to transform a message of one type to another. It is likely that
-// either FromT or ToT will be a Message on publish and SequencedMessage on subscribe.
+/**
+ * A MessageTransformer details how to transform a message of one type to another. It is likely that
+ * either FromT or ToT will be a Message on publish and SequencedMessage on subscribe.
+ */
 public interface MessageTransformer<FromT, ToT> {
+  /** Transform one message type to another. */
   ToT transform(FromT from) throws StatusException;
 }
diff --git a/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/Offset.java b/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/Offset.java
@@ -21,12 +21,15 @@
 /** An offset in the partition. */
 @AutoValue
 public abstract class Offset implements Comparable<Offset> {
+  /** Create an offset. */
   public static Offset of(long offset) {
     return new AutoValue_Offset(offset);
   }
 
+  /** The long value of this offset. */
   public abstract long value();
 
+  /** {@inheritDoc} */
   @Override
   public int compareTo(Offset o) {
     return Long.compare(value(), o.value());

diff --git a/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/Partition.java b/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/Partition.java
@@ -27,10 +27,12 @@
 public abstract class Partition implements Serializable {
   private static final long serialVersionUID = 7583927435022345L;
 
+  /** Create a partition from its long value. */
   public static Partition of(long partition) throws StatusException {
     checkArgument(partition >= 0, "Partitions are zero indexed.");
     return new AutoValue_Partition(partition);
   }
 
+  /** The long value of this partition. */
   public abstract long value();
 }
diff --git a/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/PartitionLookupUtils.java b/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/PartitionLookupUtils.java
@@ -24,9 +24,11 @@
 import io.grpc.StatusException;
 import java.util.concurrent.ExecutionException;
 
+/** Utilities for looking up information on partitions. */
 public final class PartitionLookupUtils {
   private PartitionLookupUtils() {}
 
+  /** Look up the number of partitions in a topic. */
   public static int numPartitions(TopicPath topic) throws StatusException {
     try (AdminClient client =
         AdminClient.create(
@@ -39,6 +41,7 @@ public static int numPartitions(TopicPath topic) throws StatusException {
     }
   }
 
+  /** Look up the number of partitions in a topic using the provided AdminClient. */
   public static int numPartitions(TopicPath topic, AdminClient client) throws StatusException {
     ApiFuture<Long> partitionCountFuture = client.getTopicPartitionCount(topic);
     try {
@@ -59,6 +62,7 @@ public static int numPartitions(TopicPath topic, AdminClient client) throws Stat
     }
   }
 
+  /** Look up the number of partitions in the topic associated with a subscription. */
   public static int numPartitions(SubscriptionPath subscription) throws StatusException {
     try (AdminClient client =
         AdminClient.create(
@@ -71,6 +75,10 @@ public static int numPartitions(SubscriptionPath subscription) throws StatusExce
     }
   }
 
+  /**
+   * Look up the number of partitions in the topic associated with a subscription using the provided
+   * AdminClient.
+   */
   public static int numPartitions(SubscriptionPath subscription, AdminClient client)
       throws StatusException {
     ApiFuture<Subscription> subscriptionFuture = client.getSubscription(subscription);

diff --git a/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/ProjectNumber.java b/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/ProjectNumber.java
@@ -21,10 +21,17 @@
 import com.google.auto.value.AutoValue;
 import io.grpc.StatusException;
 
+/**
+ * A wrapper class for the <a
+ * href="https://cloud.google.com/resource-manager/docs/creating-managing-projects#before_you_begin">project
+ * number</a>.
+ */
 @AutoValue
 public abstract class ProjectNumber {
+  /** The long value of this project number. */
   public abstract long value();
 
+  /** Construct a ProjectNumber from its long value. */
   public static ProjectNumber of(long value) throws StatusException {
     checkArgument(value > 0);
     return new AutoValue_ProjectNumber(value);

diff --git a/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/ProjectPath.java b/google-cloud-pubsublite/src/main/java/com/google/cloud/pubsublite/ProjectPath.java
@@ -21,10 +21,17 @@
 import com.google.auto.value.AutoValue;
 import java.io.Serializable;
 
+/**
+ * A string wrapper representing a project. Should be structured like:
+ *
+ * <p>projects/&lt;project number&gt;
+ */
 @AutoValue
 public abstract class ProjectPath implements Serializable {
+  /** The string value of this project path. */
   public abstract String value();
 
+  /** Construct a ProjectPath from its string value. */
   public static ProjectPath of(String value) {
     checkArgument(!value.isEmpty());
     return new AutoValue_ProjectPath(value);