fix(cloud-rad): move comments for TSDoc (#1423)

As we move our ref docs to cloud.google.com, we rely on TSDoc rather JSDoc.

TSDoc expects comments before the first overloaded function, we
currently have those on the last function. Those comments don't make
it into the d.ts files. We need to move comments to the first
overloaded function rather than the last one.

Internally b/190631834

Script used: https://github.com/fhinkel/cloud-rad-script/blob/main/moveComments.js

Author: fhinkel

src/iam.ts

@@ -105,9 +105,6 @@ export class IAM {
     this.id = id;
   }
 
-  getPolicy(gaxOpts?: CallOptions): Promise<GetPolicyResponse>;
-  getPolicy(callback: GetPolicyCallback): void;
-  getPolicy(gaxOpts: CallOptions, callback: GetPolicyCallback): void;
   /**
    * @typedef {array} GetPolicyResponse
    * @property {object} 0 The policy.
@@ -149,6 +146,9 @@ export class IAM {
    * });
    * ```
    */
+  getPolicy(gaxOpts?: CallOptions): Promise<GetPolicyResponse>;
+  getPolicy(callback: GetPolicyCallback): void;
+  getPolicy(gaxOpts: CallOptions, callback: GetPolicyCallback): void;
   getPolicy(
     optsOrCallback?: CallOptions | GetPolicyCallback,
     callback?: GetPolicyCallback
@@ -171,13 +171,6 @@ export class IAM {
     );
   }
 
-  setPolicy(policy: Policy, gaxOpts?: CallOptions): Promise<SetPolicyResponse>;
-  setPolicy(
-    policy: Policy,
-    gaxOpts: CallOptions,
-    callback: SetPolicyCallback
-  ): void;
-  setPolicy(policy: Policy, callback: SetPolicyCallback): void;
   /**
    * @typedef {array} SetPolicyResponse
    * @property {object} 0 The policy.
@@ -237,6 +230,13 @@ export class IAM {
    * });
    * ```
    */
+  setPolicy(policy: Policy, gaxOpts?: CallOptions): Promise<SetPolicyResponse>;
+  setPolicy(
+    policy: Policy,
+    gaxOpts: CallOptions,
+    callback: SetPolicyCallback
+  ): void;
+  setPolicy(policy: Policy, callback: SetPolicyCallback): void;
   setPolicy(
     policy: Policy,
     optsOrCallback?: CallOptions | SetPolicyCallback,
@@ -265,19 +265,6 @@ export class IAM {
     );
   }
 
-  testPermissions(
-    permissions: string | string[],
-    gaxOpts?: CallOptions
-  ): Promise<TestIamPermissionsResponse>;
-  testPermissions(
-    permissions: string | string[],
-    gaxOpts: CallOptions,
-    callback: TestIamPermissionsCallback
-  ): void;
-  testPermissions(
-    permissions: string | string[],
-    callback: TestIamPermissionsCallback
-  ): void;
   /**
    * @callback TestIamPermissionsCallback
    * @param {?Error} err Request error, if any.
@@ -356,6 +343,19 @@ export class IAM {
    * });
    * ```
    */
+  testPermissions(
+    permissions: string | string[],
+    gaxOpts?: CallOptions
+  ): Promise<TestIamPermissionsResponse>;
+  testPermissions(
+    permissions: string | string[],
+    gaxOpts: CallOptions,
+    callback: TestIamPermissionsCallback
+  ): void;
+  testPermissions(
+    permissions: string | string[],
+    callback: TestIamPermissionsCallback
+  ): void;
   testPermissions(
     permissions: string | string[],
     optsOrCallback?: CallOptions | TestIamPermissionsCallback,

src/publisher/index.ts

@@ -95,8 +95,6 @@ export class Publisher {
     this.orderedQueues = new Map();
   }
 
-  flush(): Promise<void>;
-  flush(callback: EmptyCallback): void;
   /**
    * Immediately sends all remaining queued data. This is mostly useful
    * if you are planning to call close() on the PubSub object that holds
@@ -107,6 +105,8 @@ export class Publisher {
    * @param {EmptyCallback} [callback] Callback function.
    * @returns {Promise<EmptyResponse>}
    */
+  flush(): Promise<void>;
+  flush(callback: EmptyCallback): void;
   flush(callback?: EmptyCallback): Promise<void> | void {
     const definedCallback = callback ? callback : () => {};
 
@@ -122,13 +122,6 @@ export class Publisher {
       })
       .catch(definedCallback);
   }
-  publish(data: Buffer, attributes?: Attributes): Promise<string>;
-  publish(data: Buffer, callback: PublishCallback): void;
-  publish(
-    data: Buffer,
-    attributes: Attributes,
-    callback: PublishCallback
-  ): void;
   /**
    * Publish the provided message.
    *
@@ -143,6 +136,13 @@ export class Publisher {
    * @param {PublishCallback} [callback] Callback function.
    * @returns {Promise<PublishResponse>}
    */
+  publish(data: Buffer, attributes?: Attributes): Promise<string>;
+  publish(data: Buffer, callback: PublishCallback): void;
+  publish(
+    data: Buffer,
+    attributes: Attributes,
+    callback: PublishCallback
+  ): void;
   publish(
     data: Buffer,
     attrsOrCb?: Attributes | PublishCallback,
@@ -153,8 +153,6 @@ export class Publisher {
     return this.publishMessage({data, attributes}, callback!);
   }
 
-  publishMessage(message: PubsubMessage): Promise<string>;
-  publishMessage(message: PubsubMessage, callback: PublishCallback): void;
   /**
    * Publish the provided message.
    *
@@ -166,6 +164,8 @@ export class Publisher {
    * @param {PubsubMessage} [message] Options for this message.
    * @param {PublishCallback} [callback] Callback function.
    */
+  publishMessage(message: PubsubMessage): Promise<string>;
+  publishMessage(message: PubsubMessage, callback: PublishCallback): void;
   publishMessage(
     message: PubsubMessage,
     callback?: PublishCallback

src/pubsub.ts

@@ -313,8 +313,6 @@ export class PubSub {
     return this.projectId.indexOf(PROJECT_ID_PLACEHOLDER) < 0;
   }
 
-  close(): Promise<void>;
-  close(callback: EmptyCallback): void;
   /**
    * Closes out this object, releasing any server connections. Note that once
    * you close a PubSub object, it may not be used again. Any pending operations
@@ -326,6 +324,8 @@ export class PubSub {
    * @callback EmptyCallback
    * @returns {Promise<void>}
    */
+  close(): Promise<void>;
+  close(callback: EmptyCallback): void;
   close(callback?: EmptyCallback): Promise<void> | void {
     const definedCallback = callback || (() => {});
     if (this.isOpen) {
@@ -395,22 +395,6 @@ export class PubSub {
     return new Schema(this, schemaName);
   }
 
-  createSubscription(
-    topic: Topic | string,
-    name: string,
-    options?: CreateSubscriptionOptions
-  ): Promise<CreateSubscriptionResponse>;
-  createSubscription(
-    topic: Topic | string,
-    name: string,
-    callback: CreateSubscriptionCallback
-  ): void;
-  createSubscription(
-    topic: Topic | string,
-    name: string,
-    options: CreateSubscriptionOptions,
-    callback: CreateSubscriptionCallback
-  ): void;
   /**
    * @typedef {array} CreateSubscriptionResponse
    * @property {Subscription} 0 The new {@link Subscription}.
@@ -495,6 +479,22 @@ export class PubSub {
    *   });
    * ```
    */
+  createSubscription(
+    topic: Topic | string,
+    name: string,
+    options?: CreateSubscriptionOptions
+  ): Promise<CreateSubscriptionResponse>;
+  createSubscription(
+    topic: Topic | string,
+    name: string,
+    callback: CreateSubscriptionCallback
+  ): void;
+  createSubscription(
+    topic: Topic | string,
+    name: string,
+    options: CreateSubscriptionOptions,
+    callback: CreateSubscriptionCallback
+  ): void;
   createSubscription(
     topic: Topic | string,
     name: string,
@@ -556,19 +556,6 @@ export class PubSub {
     );
   }
 
-  createTopic(
-    name: string | TopicMetadata,
-    gaxOpts?: CallOptions
-  ): Promise<CreateTopicResponse>;
-  createTopic(
-    name: string | TopicMetadata,
-    callback: CreateTopicCallback
-  ): void;
-  createTopic(
-    name: string | TopicMetadata,
-    gaxOpts: CallOptions,
-    callback: CreateTopicCallback
-  ): void;
   /**
    * @typedef {array} CreateTopicResponse
    * @property {Topic} 0 The new {@link Topic}.
@@ -611,6 +598,19 @@ export class PubSub {
    * });
    * ```
    */
+  createTopic(
+    name: string | TopicMetadata,
+    gaxOpts?: CallOptions
+  ): Promise<CreateTopicResponse>;
+  createTopic(
+    name: string | TopicMetadata,
+    callback: CreateTopicCallback
+  ): void;
+  createTopic(
+    name: string | TopicMetadata,
+    gaxOpts: CallOptions,
+    callback: CreateTopicCallback
+  ): void;
   createTopic(
     name: string | TopicMetadata,
     optsOrCallback?: CallOptions | CreateTopicCallback,
@@ -650,16 +650,6 @@ export class PubSub {
     );
   }
 
-  detachSubscription(
-    name: string,
-    gaxOpts?: CallOptions
-  ): Promise<DetachSubscriptionResponse>;
-  detachSubscription(name: string, callback: DetachSubscriptionCallback): void;
-  detachSubscription(
-    name: string,
-    gaxOpts: CallOptions,
-    callback: DetachSubscriptionCallback
-  ): void;
   /**
    * Detach a subscription with the given name.
    *
@@ -690,6 +680,16 @@ export class PubSub {
    * });
    * ```
    */
+  detachSubscription(
+    name: string,
+    gaxOpts?: CallOptions
+  ): Promise<DetachSubscriptionResponse>;
+  detachSubscription(name: string, callback: DetachSubscriptionCallback): void;
+  detachSubscription(
+    name: string,
+    gaxOpts: CallOptions,
+    callback: DetachSubscriptionCallback
+  ): void;
   detachSubscription(
     name: string,
     optsOrCallback?: CallOptions | DetachSubscriptionCallback,
@@ -823,9 +823,6 @@ export class PubSub {
     }
   }
 
-  getSnapshots(options?: PageOptions): Promise<GetSnapshotsResponse>;
-  getSnapshots(callback: GetSnapshotsCallback): void;
-  getSnapshots(options: PageOptions, callback: GetSnapshotsCallback): void;
   /**
    * Query object for listing snapshots.
    *
@@ -874,6 +871,9 @@ export class PubSub {
    * });
    * ```
    */
+  getSnapshots(options?: PageOptions): Promise<GetSnapshotsResponse>;
+  getSnapshots(callback: GetSnapshotsCallback): void;
+  getSnapshots(options: PageOptions, callback: GetSnapshotsCallback): void;
   getSnapshots(
     optsOrCallback?: PageOptions | GetSnapshotsCallback,
     callback?: GetSnapshotsCallback
@@ -926,14 +926,6 @@ export class PubSub {
     );
   }
 
-  getSubscriptions(
-    options?: GetSubscriptionsOptions
-  ): Promise<GetSubscriptionsResponse>;
-  getSubscriptions(callback: GetSubscriptionsCallback): void;
-  getSubscriptions(
-    options: GetSubscriptionsOptions,
-    callback: GetSubscriptionsCallback
-  ): void;
   /**
    * Query object for listing subscriptions.
    *
@@ -993,6 +985,14 @@ export class PubSub {
    * });
    * ```
    */
+  getSubscriptions(
+    options?: GetSubscriptionsOptions
+  ): Promise<GetSubscriptionsResponse>;
+  getSubscriptions(callback: GetSubscriptionsCallback): void;
+  getSubscriptions(
+    options: GetSubscriptionsOptions,
+    callback: GetSubscriptionsCallback
+  ): void;
   getSubscriptions(
     optsOrCallback?: GetSubscriptionsOptions | GetSubscriptionsCallback,
     callback?: GetSubscriptionsCallback
@@ -1052,9 +1052,6 @@ export class PubSub {
     );
   }
 
-  getTopics(options?: PageOptions): Promise<GetTopicsResponse>;
-  getTopics(callback: GetTopicsCallback): void;
-  getTopics(options: PageOptions, callback: GetTopicsCallback): void;
   /**
    * Query object for listing topics.
    *
@@ -1113,6 +1110,9 @@ export class PubSub {
    * });
    * ```
    */
+  getTopics(options?: PageOptions): Promise<GetTopicsResponse>;
+  getTopics(callback: GetTopicsCallback): void;
+  getTopics(options: PageOptions, callback: GetTopicsCallback): void;
   getTopics(
     optsOrCallback?: PageOptions | GetTopicsCallback,
     callback?: GetTopicsCallback