Minor javadoc fixes

gcloud-java-core/src/main/java/com/google/cloud/AsyncPage.java

@@ -37,15 +37,16 @@
  *   for (T value : page.values()) {
  *     // do something with value
  *   }
- *   page = page.nextPage().get();
+ *   page = page.nextPageAsync().get();
  * }}</pre>
  *
  * @param <T> the value type that the page holds
  */
 public interface AsyncPage<T> extends Page<T> {
 
   /**
-   * Returns a {@link Future} object for the next page.
+   * Returns a {@link Future} object for the next page. {@link Future#get()} returns {@code null} if
+   * the last page has been reached.
    */
   Future<AsyncPage<T>> nextPageAsync();
 }

gcloud-java-core/src/main/java/com/google/cloud/AsyncPageImpl.java

@@ -17,6 +17,7 @@
 package com.google.cloud;
 
 import com.google.common.base.Throwables;
+import com.google.common.util.concurrent.Futures;
 import com.google.common.util.concurrent.Uninterruptibles;
 
 import java.io.Serializable;
@@ -47,7 +48,7 @@ private static class SyncNextPageFetcher<T> implements PageImpl.NextPageFetcher<
 
     private static final long serialVersionUID = -4124568632363525351L;
 
-    private NextPageFetcher<T> asyncPageFetcher;
+    private final NextPageFetcher<T> asyncPageFetcher;
 
     private SyncNextPageFetcher(NextPageFetcher<T> asyncPageFetcher) {
       this.asyncPageFetcher = asyncPageFetcher;
@@ -75,7 +76,7 @@ public AsyncPageImpl(NextPageFetcher<T> asyncPageFetcher, String cursor, Iterabl
   @Override
   public Future<AsyncPage<T>> nextPageAsync() {
     if (nextPageCursor() == null || asyncPageFetcher == null) {
-      return null;
+      return Futures.immediateCheckedFuture(null);
     }
     return asyncPageFetcher.nextPage();
   }

gcloud-java-pubsub/src/main/java/com/google/cloud/pubsub/SubscriptionId.java

@@ -28,8 +28,8 @@
 /**
  * Identity for a Google PubSub subscription. {@code SubscriptionId} objects are returned by the
  * {@link PubSub#listSubscriptions(String, PubSub.ListOption...)} and
- * {@link PubSub#listSubscriptionsAsync(String, PubSub.ListOption...)} methods as the same topic
- * can be used by subscriptions in different projects.
+ * {@link PubSub#listSubscriptionsAsync(String, PubSub.ListOption...)} methods as a topic may have
+ * subscriptions from different projects.
  */
 public class SubscriptionId implements Serializable {
 

gcloud-java-pubsub/src/main/java/com/google/cloud/pubsub/SubscriptionInfo.java

@@ -291,7 +291,7 @@ public Builder toBuilder() {
    *     letters ({@code [A-Za-z]}), numbers ({@code [0-9]}), dashes ({@code -}), underscores
    *     ({@code _}), periods ({@code .}), tildes ({@code ~}), plus ({@code +}) or percent signs
    *     ({@code %}). It must be between 3 and 255 characters in length and cannot begin with the
-   *     string {@code goog}
+   *     string {@code goog}.
    */
   public static SubscriptionInfo of(String topic, String name) {
     return builder(topic, name).build();
@@ -307,7 +307,7 @@ public static SubscriptionInfo of(String topic, String name) {
    *     letters ({@code [A-Za-z]}), numbers ({@code [0-9]}), dashes ({@code -}), underscores
    *     ({@code _}), periods ({@code .}), tildes ({@code ~}), plus ({@code +}) or percent signs
    *     ({@code %}). It must be between 3 and 255 characters in length and cannot begin with the
-   *     string {@code goog}
+   *     string {@code goog}.
    */
   public static SubscriptionInfo of(TopicId topic, String name) {
     return builder(topic, name).build();
@@ -323,7 +323,7 @@ public static SubscriptionInfo of(TopicId topic, String name) {
    *     letters ({@code [A-Za-z]}), numbers ({@code [0-9]}), dashes ({@code -}), underscores
    *     ({@code _}), periods ({@code .}), tildes ({@code ~}), plus ({@code +}) or percent signs
    *     ({@code %}). It must be between 3 and 255 characters in length and cannot begin with the
-   *     string {@code goog}
+   *     string {@code goog}.
    * @param endpoint a URL locating the endpoint to which messages should be pushed. For example,
    *     an endpoint might use {@code https://example.com/push}.
    */
@@ -341,7 +341,7 @@ public static SubscriptionInfo of(String topic, String name, String endpoint) {
    *     letters ({@code [A-Za-z]}), numbers ({@code [0-9]}), dashes ({@code -}), underscores
    *     ({@code _}), periods ({@code .}), tildes ({@code ~}), plus ({@code +}) or percent signs
    *     ({@code %}). It must be between 3 and 255 characters in length and cannot begin with the
-   *     string {@code goog}
+   *     string {@code goog}.
    * @param endpoint a URL locating the endpoint to which messages should be pushed. For example,
    *     an endpoint might use {@code https://example.com/push}.
    */
@@ -359,7 +359,7 @@ public static SubscriptionInfo of(TopicId topic, String name, String endpoint) {
    *     letters ({@code [A-Za-z]}), numbers ({@code [0-9]}), dashes ({@code -}), underscores
    *     ({@code _}), periods ({@code .}), tildes ({@code ~}), plus ({@code +}) or percent signs
    *     ({@code %}). It must be between 3 and 255 characters in length and cannot begin with the
-   *     string {@code goog}
+   *     string {@code goog}.
    */
   public static Builder builder(String topic, String name) {
     return builder(TopicId.of(topic), name);
@@ -375,7 +375,7 @@ public static Builder builder(String topic, String name) {
    *     letters ({@code [A-Za-z]}), numbers ({@code [0-9]}), dashes ({@code -}), underscores
    *     ({@code _}), periods ({@code .}), tildes ({@code ~}), plus ({@code +}) or percent signs
    *     ({@code %}). It must be between 3 and 255 characters in length and cannot begin with the
-   *     string {@code goog}
+   *     string {@code goog}.
    */
   public static Builder builder(TopicId topic, String name) {
     return new BuilderImpl(topic, name);

gcloud-java-pubsub/src/main/java/com/google/cloud/pubsub/TopicId.java

@@ -28,7 +28,7 @@
 
 /**
  * Identity for a Google PubSub topic. A {@code TopicId} object can be used to create subscriptions
- * for topics, possibly residing on a different project.
+ * for topics that possibly reside in different projects.
  */
 public final class TopicId implements Serializable {
 
@@ -43,7 +43,8 @@ private TopicId(String project, String topic) {
   }
 
   /**
-   * Returns the name of the project where the topic resides.
+   * Returns the name of the project where the topic resides. If {@code null} the topic is assumed
+   * to reside in the {@link PubSubOptions#projectId()} project.
    */
   public String project() {
     return project;

gcloud-java-pubsub/src/main/java/com/google/cloud/pubsub/TopicInfo.java

@@ -140,7 +140,7 @@ public Builder toBuilder() {
    *     ({@code [A-Za-z]}), numbers ({@code [0-9]}), dashes ({@code -}), underscores ({@code _}),
    *     periods ({@code .}), tildes ({@code ~}), plus ({@code +}) or percent signs ({@code %}).
    *     It must be between 3 and 255 characters in length and cannot begin with the string
-   *     {@code goog}
+   *     {@code goog}.
    */
   public static TopicInfo of(String name) {
     return builder(name).build();
@@ -153,7 +153,7 @@ public static TopicInfo of(String name) {
    *     ({@code [A-Za-z]}), numbers ({@code [0-9]}), dashes ({@code -}), underscores ({@code _}),
    *     periods ({@code .}), tildes ({@code ~}), plus ({@code +}) or percent signs ({@code %}).
    *     It must be between 3 and 255 characters in length and cannot begin with the string
-   *     {@code goog}
+   *     {@code goog}.
    */
   public static Builder builder(String name) {
     return new BuilderImpl(name);