Fixing doc problems, improving formatting

fixes googleapis#387 - Moving references of delete topics to get/list calls
fixes googleapis#386 - Removing the problematic wording
fixes googleapis#385 - Changing 'returns' to 'generates' when referencing errors

Author: garrettjonesgoogle

gcloud-java-pubsub/src/main/java/com/google/gcloud/pubsub/spi/PublisherApi.java

@@ -447,7 +447,7 @@ public ApiCallable<Topic, Topic> createTopicCallable() {
 
   // AUTO-GENERATED DOCUMENTATION AND METHOD - see instructions at the top of the file for editing.
   /**
-   * Adds one or more messages to the topic. Returns `NOT_FOUND` if the topic
+   * Adds one or more messages to the topic. Generates `NOT_FOUND` if the topic
    * does not exist. The message payload must not be empty; it must contain
    *  either a non-empty data field, or at least one attribute.
    *
@@ -466,7 +466,7 @@ public PublishResponse publish(String topic, List<PubsubMessage> messages) {
 
   // AUTO-GENERATED DOCUMENTATION AND METHOD - see instructions at the top of the file for editing.
   /**
-   * Adds one or more messages to the topic. Returns `NOT_FOUND` if the topic
+   * Adds one or more messages to the topic. Generates `NOT_FOUND` if the topic
    * does not exist. The message payload must not be empty; it must contain
    *  either a non-empty data field, or at least one attribute.
    *
@@ -481,7 +481,7 @@ public PublishResponse publish(PublishRequest request) {
 
   // AUTO-GENERATED DOCUMENTATION AND METHOD - see instructions at the top of the file for editing.
   /**
-   * Adds one or more messages to the topic. Returns `NOT_FOUND` if the topic
+   * Adds one or more messages to the topic. Generates `NOT_FOUND` if the topic
    * does not exist. The message payload must not be empty; it must contain
    *  either a non-empty data field, or at least one attribute.
    *
@@ -659,7 +659,7 @@ public Iterable<String> listTopicSubscriptions(ListTopicSubscriptionsRequest req
 
   // AUTO-GENERATED DOCUMENTATION AND METHOD - see instructions at the top of the file for editing.
   /**
-   * Deletes the topic with the given name. Returns `NOT_FOUND` if the topic
+   * Deletes the topic with the given name. Generates `NOT_FOUND` if the topic
    * does not exist. After a topic is deleted, a new topic may be created with
    * the same name; this is an entirely new topic with none of the old
    * configuration or subscriptions. Existing subscriptions to this topic are
@@ -678,7 +678,7 @@ public void deleteTopic(String topic) {
 
   // AUTO-GENERATED DOCUMENTATION AND METHOD - see instructions at the top of the file for editing.
   /**
-   * Deletes the topic with the given name. Returns `NOT_FOUND` if the topic
+   * Deletes the topic with the given name. Generates `NOT_FOUND` if the topic
    * does not exist. After a topic is deleted, a new topic may be created with
    * the same name; this is an entirely new topic with none of the old
    * configuration or subscriptions. Existing subscriptions to this topic are
@@ -695,7 +695,7 @@ public void deleteTopic(DeleteTopicRequest request) {
 
   // AUTO-GENERATED DOCUMENTATION AND METHOD - see instructions at the top of the file for editing.
   /**
-   * Deletes the topic with the given name. Returns `NOT_FOUND` if the topic
+   * Deletes the topic with the given name. Generates `NOT_FOUND` if the topic
    * does not exist. After a topic is deleted, a new topic may be created with
    * the same name; this is an entirely new topic with none of the old
    * configuration or subscriptions. Existing subscriptions to this topic are

gcloud-java-pubsub/src/main/java/com/google/gcloud/pubsub/spi/SubscriberApi.java

@@ -382,8 +382,8 @@ public static final String extractSubscriptionFromSubscriptionPath(String subscr
   // AUTO-GENERATED DOCUMENTATION AND METHOD - see instructions at the top of the file for editing.
   /**
    * Creates a subscription to a given topic for a given subscriber.
-   * If the subscription already exists, returns `ALREADY_EXISTS`.
-   * If the corresponding topic doesn't exist, returns `NOT_FOUND`.
+   * If the subscription already exists, generates `ALREADY_EXISTS`.
+   * If the corresponding topic doesn't exist, generates `NOT_FOUND`.
    *
    * If the name is not provided in the request, the server will assign a random
    * name for this subscription on the same project as the topic.
@@ -398,8 +398,6 @@ public static final String extractSubscriptionFromSubscriptionPath(String subscr
    * plus (`+`) or percent signs (`%`). It must be between 3 and 255 characters
    * in length, and it must not start with `"goog"`.
    * @param topic The name of the topic from which this subscription is receiving messages.
-   * The value of this field will be `_deleted-topic_` if the topic has been
-   * deleted.
    * @param pushConfig If push delivery is used with this subscription, this field is
    * used to configure it. An empty `pushConfig` signifies that the subscriber
    * will pull and ack messages using API methods.
@@ -438,8 +436,8 @@ public Subscription createSubscription(
   // AUTO-GENERATED DOCUMENTATION AND METHOD - see instructions at the top of the file for editing.
   /**
    * Creates a subscription to a given topic for a given subscriber.
-   * If the subscription already exists, returns `ALREADY_EXISTS`.
-   * If the corresponding topic doesn't exist, returns `NOT_FOUND`.
+   * If the subscription already exists, generates `ALREADY_EXISTS`.
+   * If the corresponding topic doesn't exist, generates `NOT_FOUND`.
    *
    * If the name is not provided in the request, the server will assign a random
    * name for this subscription on the same project as the topic.
@@ -456,8 +454,8 @@ public Subscription createSubscription(Subscription request) {
   // AUTO-GENERATED DOCUMENTATION AND METHOD - see instructions at the top of the file for editing.
   /**
    * Creates a subscription to a given topic for a given subscriber.
-   * If the subscription already exists, returns `ALREADY_EXISTS`.
-   * If the corresponding topic doesn't exist, returns `NOT_FOUND`.
+   * If the subscription already exists, generates `ALREADY_EXISTS`.
+   * If the corresponding topic doesn't exist, generates `NOT_FOUND`.
    *
    * If the name is not provided in the request, the server will assign a random
    * name for this subscription on the same project as the topic.
@@ -481,6 +479,9 @@ public ApiCallable<Subscription, Subscription> createSubscriptionCallable() {
   /**
    * Gets the configuration details of a subscription.
    *
+   * If the topic of a subscription has been deleted, the subscription itself is
+   * not deleted, but the value of the `topic` field is set to `_deleted-topic_`.
+   *
    * <!-- manual edit -->
    * <!-- end manual edit -->
    *
@@ -497,6 +498,9 @@ public Subscription getSubscription(String subscription) {
   /**
    * Gets the configuration details of a subscription.
    *
+   * If the topic of a subscription has been deleted, the subscription itself is
+   * not deleted, but the value of the `topic` field is set to `_deleted-topic_`.
+   *
    * <!-- manual edit -->
    * <!-- end manual edit -->
    *
@@ -510,6 +514,9 @@ public Subscription getSubscription(GetSubscriptionRequest request) {
   /**
    * Gets the configuration details of a subscription.
    *
+   * If the topic of a subscription has been deleted, the subscription itself is
+   * not deleted, but the value of the `topic` field is set to `_deleted-topic_`.
+   *
    * <!-- manual edit -->
    * <!-- end manual edit -->
    */
@@ -529,6 +536,9 @@ public ApiCallable<GetSubscriptionRequest, Subscription> getSubscriptionCallable
   /**
    * Lists matching subscriptions.
    *
+   * If the topic of a subscription has been deleted, the subscription itself is
+   * not deleted, but the value of the `topic` field is set to `_deleted-topic_`.
+   *
    * <!-- manual edit -->
    * <!-- end manual edit -->
    */
@@ -542,6 +552,9 @@ public Iterable<Subscription> listSubscriptions(String project) {
   /**
    * Lists matching subscriptions.
    *
+   * If the topic of a subscription has been deleted, the subscription itself is
+   * not deleted, but the value of the `topic` field is set to `_deleted-topic_`.
+   *
    * <!-- manual edit -->
    * <!-- end manual edit -->
    *
@@ -555,6 +568,9 @@ public Iterable<Subscription> listSubscriptions(ListSubscriptionsRequest request
   /**
    * Lists matching subscriptions.
    *
+   * If the topic of a subscription has been deleted, the subscription itself is
+   * not deleted, but the value of the `topic` field is set to `_deleted-topic_`.
+   *
    * <!-- manual edit -->
    * <!-- end manual edit -->
    */
@@ -567,6 +583,9 @@ public Iterable<Subscription> listSubscriptions(ListSubscriptionsRequest request
   /**
    * Lists matching subscriptions.
    *
+   * If the topic of a subscription has been deleted, the subscription itself is
+   * not deleted, but the value of the `topic` field is set to `_deleted-topic_`.
+   *
    * <!-- manual edit -->
    * <!-- end manual edit -->
    */
@@ -586,7 +605,7 @@ public Iterable<Subscription> listSubscriptions(ListSubscriptionsRequest request
   // AUTO-GENERATED DOCUMENTATION AND METHOD - see instructions at the top of the file for editing.
   /**
    * Deletes an existing subscription. All pending messages in the subscription
-   * are immediately dropped. Calls to `Pull` after deletion will return
+   * are immediately dropped. Calls to `Pull` after deletion will generate
    * `NOT_FOUND`. After a subscription is deleted, a new one may be created with
    * the same name, but the new one has no association with the old
    * subscription, or its topic unless the same topic is specified.
@@ -606,7 +625,7 @@ public void deleteSubscription(String subscription) {
   // AUTO-GENERATED DOCUMENTATION AND METHOD - see instructions at the top of the file for editing.
   /**
    * Deletes an existing subscription. All pending messages in the subscription
-   * are immediately dropped. Calls to `Pull` after deletion will return
+   * are immediately dropped. Calls to `Pull` after deletion will generate
    * `NOT_FOUND`. After a subscription is deleted, a new one may be created with
    * the same name, but the new one has no association with the old
    * subscription, or its topic unless the same topic is specified.
@@ -623,7 +642,7 @@ public void deleteSubscription(DeleteSubscriptionRequest request) {
   // AUTO-GENERATED DOCUMENTATION AND METHOD - see instructions at the top of the file for editing.
   /**
    * Deletes an existing subscription. All pending messages in the subscription
-   * are immediately dropped. Calls to `Pull` after deletion will return
+   * are immediately dropped. Calls to `Pull` after deletion will generate
    * `NOT_FOUND`. After a subscription is deleted, a new one may be created with
    * the same name, but the new one has no association with the old
    * subscription, or its topic unless the same topic is specified.
@@ -780,7 +799,7 @@ public ApiCallable<AcknowledgeRequest, Empty> acknowledgeCallable() {
   // AUTO-GENERATED DOCUMENTATION AND METHOD - see instructions at the top of the file for editing.
   /**
    * Pulls messages from the server. Returns an empty list if there are no
-   * messages available in the backlog. The server may return `UNAVAILABLE` if
+   * messages available in the backlog. The server may generate `UNAVAILABLE` if
    * there are too many concurrent pull requests pending for the given
    * subscription.
    *
@@ -791,8 +810,7 @@ public ApiCallable<AcknowledgeRequest, Empty> acknowledgeCallable() {
    * @param returnImmediately If this is specified as true the system will respond immediately even if
    * it is not able to return a message in the `Pull` response. Otherwise the
    * system is allowed to wait until at least one message is available rather
-   * than returning no messages. The client may cancel the request if it does
-   * not wish to wait any longer for the response.
+   * than returning no messages.
    * @param maxMessages The maximum number of messages returned for this request. The Pub/Sub
    * system may return fewer than the number specified.
    */
@@ -810,7 +828,7 @@ public PullResponse pull(String subscription, boolean returnImmediately, int max
   // AUTO-GENERATED DOCUMENTATION AND METHOD - see instructions at the top of the file for editing.
   /**
    * Pulls messages from the server. Returns an empty list if there are no
-   * messages available in the backlog. The server may return `UNAVAILABLE` if
+   * messages available in the backlog. The server may generate `UNAVAILABLE` if
    * there are too many concurrent pull requests pending for the given
    * subscription.
    *
@@ -826,7 +844,7 @@ public PullResponse pull(PullRequest request) {
   // AUTO-GENERATED DOCUMENTATION AND METHOD - see instructions at the top of the file for editing.
   /**
    * Pulls messages from the server. Returns an empty list if there are no
-   * messages available in the backlog. The server may return `UNAVAILABLE` if
+   * messages available in the backlog. The server may generate `UNAVAILABLE` if
    * there are too many concurrent pull requests pending for the given
    * subscription.
    *

gcloud-java-pubsub/src/main/java/com/google/gcloud/pubsub/spi/testing/LocalPublisherImpl.java

@@ -74,7 +74,8 @@ public void getTopic(GetTopicRequest request, StreamObserver<Topic> responseObse
   }
 
   @Override
-  public void listTopics(ListTopicsRequest request, StreamObserver<ListTopicsResponse> responseObserver) {
+  public void listTopics(
+      ListTopicsRequest request, StreamObserver<ListTopicsResponse> responseObserver) {
     List<Topic> responseTopics = new ArrayList<>();
     for (String topicName : topics.keySet()) {
       String projectOfTopic = PublisherApi.extractProjectFromTopicPath(topicName);
@@ -84,11 +85,14 @@ public void listTopics(ListTopicsRequest request, StreamObserver<ListTopicsRespo
         responseTopics.add(topicObj);
       }
     }
-    Collections.sort(responseTopics, new Comparator<Topic>() {
-      @Override public int compare(Topic o1, Topic o2) {
-        return o1.getName().compareTo(o2.getName());
-      }
-    });
+    Collections.sort(
+        responseTopics,
+        new Comparator<Topic>() {
+          @Override
+          public int compare(Topic o1, Topic o2) {
+            return o1.getName().compareTo(o2.getName());
+          }
+        });
     ListTopicsResponse.Builder response = ListTopicsResponse.newBuilder();
     response.setNextPageToken("");
     response.addAllTopics(responseTopics);
@@ -97,7 +101,8 @@ public void listTopics(ListTopicsRequest request, StreamObserver<ListTopicsRespo
   }
 
   @Override
-  public void listTopicSubscriptions(ListTopicSubscriptionsRequest request,
+  public void listTopicSubscriptions(
+      ListTopicSubscriptionsRequest request,
       StreamObserver<ListTopicSubscriptionsResponse> responseObserver) {
     responseObserver.onNext(ListTopicSubscriptionsResponse.getDefaultInstance());
     responseObserver.onCompleted();

gcloud-java-pubsub/src/main/java/com/google/gcloud/pubsub/testing/LocalPubsubHelper.java

@@ -61,8 +61,7 @@ public class LocalPubsubHelper {
   public LocalPubsubHelper() throws MalformedURLException {
     gcloudCommand = new ArrayList<>(Arrays.asList(GCLOUD_CMD_TEXT.split(" ")));
     gcloudCommand.add(DEFAULT_HOST);
-    emulatorUrl =
-        new URL("http://storage.googleapis.com/pubsub/tools/" + FILENAME);
+    emulatorUrl = new URL("http://storage.googleapis.com/pubsub/tools/" + FILENAME);
     GCloudEmulatorRunner gcloudRunner =
         new GCloudEmulatorRunner(gcloudCommand, VERSION_PREFIX, MIN_VERSION);
     DownloadableEmulatorRunner downloadRunner =
@@ -105,8 +104,7 @@ public void stop() throws IOException, InterruptedException {
    * Creates a channel for making requests to the in-memory service.
    */
   public ManagedChannel createChannel() {
-    return NettyChannelBuilder
-        .forAddress(DEFAULT_HOST, DEFAULT_PORT)
+    return NettyChannelBuilder.forAddress(DEFAULT_HOST, DEFAULT_PORT)
         .negotiationType(NegotiationType.PLAINTEXT)
         .build();
   }