Document generic types

Ajay Kannan · Ajay Kannan · commit 50469be964e5 · 2015-12-30T09:28:59.000-08:00
diff --git a/gcloud-java-bigquery/src/main/java/com/google/gcloud/bigquery/BaseTableInfo.java b/gcloud-java-bigquery/src/main/java/com/google/gcloud/bigquery/BaseTableInfo.java
@@ -94,6 +94,12 @@ public enum Type {
   private final Long expirationTime;
   private final Long lastModifiedTime;
 
+  /**
+   * Base builder for tables.
+   *
+   * @param <T> the table type.
+   * @param <B> the table builder.
+   */
   public abstract static class Builder<T extends BaseTableInfo, B extends Builder<T, B>> {
 
     private String etag;
diff --git a/gcloud-java-bigquery/src/main/java/com/google/gcloud/bigquery/JobInfo.java b/gcloud-java-bigquery/src/main/java/com/google/gcloud/bigquery/JobInfo.java
@@ -32,6 +32,8 @@
  * a table. Use {@link QueryJobInfo} for a job that runs a query.
  *
  * @see <a href="https://cloud.google.com/bigquery/docs/reference/v2/jobs">Jobs</a>
+ *
+ * @param <S> the statistics type.
  */
 public abstract class JobInfo<S extends JobStatistics> implements Serializable {
 
@@ -87,6 +89,13 @@ public enum WriteDisposition {
   private final S statistics;
   private final String userEmail;
 
+  /**
+   * Base builder for jobs.
+   *
+   * @param <T> the job type.
+   * @param <S> the job statistics type.
+   * @param <B> the job builder.
+   */
   public abstract static class Builder<T extends JobInfo, S extends JobStatistics,
       B extends Builder<T, S, B>> {
 
diff --git a/gcloud-java-core/src/main/java/com/google/gcloud/BaseService.java b/gcloud-java-core/src/main/java/com/google/gcloud/BaseService.java
@@ -16,6 +16,11 @@
 
 package com.google.gcloud;
 
+/**
+ * Base class for service objects.
+ *
+ * @param <OptionsT> the {@code ServiceOptions} subclass corresponding to the service.
+ */
 public abstract class BaseService<OptionsT extends ServiceOptions<?, ?, OptionsT>>
     implements Service<OptionsT> {
 
diff --git a/gcloud-java-core/src/main/java/com/google/gcloud/Page.java b/gcloud-java-core/src/main/java/com/google/gcloud/Page.java
@@ -40,6 +40,8 @@
  *   }
  *   page = page.nextPage();
  * }}</pre>
+ *
+ * @param <T> the value type that the page holds.
  */
 public interface Page<T> {
 
diff --git a/gcloud-java-core/src/main/java/com/google/gcloud/PageImpl.java b/gcloud-java-core/src/main/java/com/google/gcloud/PageImpl.java
@@ -25,6 +25,8 @@
 
 /**
  * Base implementation for Google Cloud paginated results.
+ *
+ * @param <T> the value type that the page holds.
  */
 public class PageImpl<T> implements Page<T>, Serializable {
 
@@ -34,6 +36,11 @@ public class PageImpl<T> implements Page<T>, Serializable {
   private final Iterable<T> results;
   private final NextPageFetcher<T> pageFetcher;
 
+  /**
+   * Interface for fetching the next page of results from the service.
+   *
+   * @param <T> the value type that the page holds.
+   */
   public interface NextPageFetcher<T> extends Serializable {
     Page<T> nextPage();
   }
diff --git a/gcloud-java-core/src/main/java/com/google/gcloud/Restorable.java b/gcloud-java-core/src/main/java/com/google/gcloud/Restorable.java
@@ -33,6 +33,8 @@
  * X restorableObj = state.restore();
  * ...
  * }</pre>
+ *
+ * @param <T> the restorable object's type.
  */
 public interface Restorable<T extends Restorable<T>> {
 
diff --git a/gcloud-java-core/src/main/java/com/google/gcloud/RestorableState.java b/gcloud-java-core/src/main/java/com/google/gcloud/RestorableState.java
@@ -22,6 +22,8 @@
  *
  * Implementations of this class must implement {@link java.io.Serializable} to ensure that the
  * state of a the object can be correctly serialized.
+ *
+ * @param <T> the restored object's type.
  */
 public interface RestorableState<T extends Restorable<T>> {
 
diff --git a/gcloud-java-core/src/main/java/com/google/gcloud/Service.java b/gcloud-java-core/src/main/java/com/google/gcloud/Service.java
@@ -16,6 +16,11 @@
 
 package com.google.gcloud;
 
+/**
+ * Interface for service objects.
+ *
+ * @param <OptionsT> the {@code ServiceOptions} subclass corresponding to the service.
+ */
 public interface Service<OptionsT extends ServiceOptions<?, ?, OptionsT>> {
   OptionsT options();
 }
diff --git a/gcloud-java-core/src/main/java/com/google/gcloud/ServiceFactory.java b/gcloud-java-core/src/main/java/com/google/gcloud/ServiceFactory.java
@@ -19,8 +19,11 @@
 /**
  * A base interface for all service factories.
  *
- * Implementation must provide a public no-arg constructor.
+ * <p>Implementation must provide a public no-arg constructor.
  * Loading of a factory implementation is done via {@link java.util.ServiceLoader}.
+ *
+ * @param <ServiceT> the service subclass.
+ * @param <ServiceOptionsT> the {@code ServiceOptions} subclass corresponding to the service.
  */
 @SuppressWarnings("rawtypes")
 public interface ServiceFactory<ServiceT extends Service, ServiceOptionsT extends ServiceOptions> {
diff --git a/gcloud-java-core/src/main/java/com/google/gcloud/ServiceOptions.java b/gcloud-java-core/src/main/java/com/google/gcloud/ServiceOptions.java
@@ -53,6 +53,13 @@
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
+/**
+ * Abstract class representing service options.
+ *
+ * @param <ServiceT> the service subclass.
+ * @param <ServiceRpcT> the spi-layer class corresponding to the service.
+ * @param <OptionsT> the {@code ServiceOptions} subclass corresponding to the service.
+ */
 public abstract class ServiceOptions<ServiceT extends Service<OptionsT>, ServiceRpcT,
     OptionsT extends ServiceOptions<ServiceT, ServiceRpcT, OptionsT>> implements Serializable {
 
@@ -150,6 +157,14 @@ private Object readResolve() throws ObjectStreamException {
     }
   }
 
+  /**
+   * Builder for {@code ServiceOptions}.
+   *
+   * @param <ServiceT> the service subclass.
+   * @param <ServiceRpcT> the spi-layer class corresponding to the service.
+   * @param <OptionsT> the {@code ServiceOptions} subclass corresponding to the service.
+   * @param <B> the {@code ServiceOptions} builder.
+   */
   protected abstract static class Builder<ServiceT extends Service<OptionsT>, ServiceRpcT,
       OptionsT extends ServiceOptions<ServiceT, ServiceRpcT, OptionsT>,
       B extends Builder<ServiceT, ServiceRpcT, OptionsT, B>> {
diff --git a/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/BaseKey.java b/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/BaseKey.java
@@ -39,7 +39,12 @@ abstract class BaseKey extends Serializable<DatastoreV1.Key> {
   private final transient String namespace;
   private final transient ImmutableList<PathElement> path;
 
-  abstract static class Builder<B extends Builder<B>> {
+  /**
+   * Base class for key builders.
+   *
+   * @param <B> the key builder.
+   */
+  protected abstract static class Builder<B extends Builder<B>> {
 
     String projectId;
     String namespace;
diff --git a/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/StructuredQuery.java b/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/StructuredQuery.java
@@ -609,7 +609,13 @@ public static Projection first(String property) {
     }
   }
 
-  static class BaseBuilder<V, B extends BaseBuilder<V, B>> {
+  /**
+   * Base class for StructuredQuery builders.
+   *
+   * @param <V> the type of result the query returns.
+   * @param <B> the query builder.
+   */
+  protected static class BaseBuilder<V, B extends BaseBuilder<V, B>> {
 
     private final ResultType<V> resultType;
     private String namespace;
diff --git a/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/ValueBuilder.java b/gcloud-java-datastore/src/main/java/com/google/gcloud/datastore/ValueBuilder.java
@@ -18,6 +18,10 @@
 
 /**
  * A common interface for Value builders.
+ *
+ * @param <V> the data type that the {@code Value} object holds.
+ * @param <P> the value type.
+ * @param <B> the value type's associated builder.
  */
 public interface ValueBuilder<V, P extends Value<V>, B extends ValueBuilder<V, P, B>> {
 

Original file line number	Diff line number	Diff line change
`@@ -22,6 +22,8 @@`
`22`	`22`	`*`
`23`	`23`	`* Implementations of this class must implement {@link java.io.Serializable} to ensure that the`
`24`	`24`	`* state of a the object can be correctly serialized.`
	`25`	`+ *`
	`26`	`+ * @param <T> the restored object's type.`
`25`	`27`	`*/`
`26`	`28`	`public interface RestorableState<T extends Restorable<T>> {`
`27`	`29`