fix: Add Documentation (#221)

* fix: Add javadoc to public classes. * fix: Reformat. * fix: Suggested docs changes. * fix: Fix mvn site issues.

Author: dpcollins-google

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();
  }
 

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();
 }

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());

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()

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";
  }

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(

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);

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);

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();
  }
 }

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;
 }