fix(docs): ensure docs are not removed by typescript

src/iam.ts

@@ -23,46 +23,21 @@ import * as arrify from 'arrify';
 import {CallOptions} from 'google-gax';
 import {PubSub} from '.';
 
-/**
- * @callback GetPolicyCallback
- * @param {?Error} err Request error, if any.
- * @param {object} acl The policy.
- */
 export interface GetPolicyCallback {
   (err?: Error|null, acl?: Policy|null): void;
 }
 
-/**
- * @callback SetPolicyCallback
- * @param {?Error} err Request error, if any.
- * @param {object} acl The policy.
- */
 export interface SetPolicyCallback {
   (err?: Error|null, acl?: Policy|null): void;
 }
 
-/**
- * @typedef {array} SetPolicyResponse
- * @property {object} 0 The policy.
- */
 export type SetPolicyResponse = [Policy];
-
-/**
- * @typedef {array} GetPolicyResponse
- * @property {object} 0 The policy.
- */
 export type GetPolicyResponse = [Policy];
 
-/**
- * @typedef {string[]} PermissionsResponse
- * A subset of TestPermissionsRequest.permissions that the caller is allowed.
- * @see https://cloud.google.com/pubsub/docs/reference/rpc/google.iam.v1#google.iam.v1.TestIamPermissionsRequest
- */
 export interface PermissionsResponse {
   permissions: string|string[];
 }
 
-
 /**
  * Shows which IAM permissions is allowed.
  * The key to this object are the IAM permissions (string) and the values are
@@ -72,19 +47,8 @@ export type IamPermissionsMap = {
   [key: string]: boolean
 };
 
-/**
- * @typedef {array} TestIamPermissionsResponse
- * @property {object[]} 0 A subset of permissions that the caller is allowed.
- * @property {PermissionsResponse} 1 The full API response.
- */
 export type TestIamPermissionsResponse = [PermissionsResponse];
 
-/**
- * @callback TestIamPermissionsCallback
- * @param {?Error} err Request error, if any.
- * @param {TestIamPermissionsAPIResponse} permissions A subset of permissions that the caller is allowed.
- * @param {PermissionsResponse} apiResponse The full API response.
- */
 export interface TestIamPermissionsCallback {
   (err?: Error|null, permissions?: IamPermissionsMap|null,
    apiResponse?: PermissionsResponse): void;
@@ -179,6 +143,15 @@ export class IAM {
   getPolicy(gaxOpts?: CallOptions): Promise<GetPolicyResponse>;
   getPolicy(callback: GetPolicyCallback): void;
   getPolicy(gaxOpts: CallOptions, callback: GetPolicyCallback): void;
+  /**
+   * @typedef {array} GetPolicyResponse
+   * @property {object} 0 The policy.
+   */
+  /**
+   * @callback GetPolicyCallback
+   * @param {?Error} err Request error, if any.
+   * @param {object} acl The policy.
+   */
   /**
    * Get the IAM policy
    *
@@ -235,6 +208,15 @@ export class IAM {
   setPolicy(policy: Policy, gaxOpts: CallOptions, callback: SetPolicyCallback):
       void;
   setPolicy(policy: Policy, callback: SetPolicyCallback): void;
+  /**
+   * @typedef {array} SetPolicyResponse
+   * @property {object} 0 The policy.
+   */
+  /**
+   * @callback SetPolicyCallback
+   * @param {?Error} err Request error, if any.
+   * @param {object} acl The policy.
+   */
   /**
    * Set the IAM policy
    *
@@ -317,6 +299,22 @@ export class IAM {
       callback: TestIamPermissionsCallback): void;
   testPermissions(
       permissions: string|string[], callback: TestIamPermissionsCallback): void;
+  /**
+   * @callback TestIamPermissionsCallback
+   * @param {?Error} err Request error, if any.
+   * @param {TestIamPermissionsAPIResponse} permissions A subset of permissions that the caller is allowed.
+   * @param {PermissionsResponse} apiResponse The full API response.
+   */
+  /**
+   * @typedef {array} TestIamPermissionsResponse
+   * @property {object[]} 0 A subset of permissions that the caller is allowed.
+   * @property {PermissionsResponse} 1 The full API response.
+   */
+  /**
+   * @typedef {string[]} PermissionsResponse
+   * A subset of TestPermissionsRequest.permissions that the caller is allowed.
+   * @see https://cloud.google.com/pubsub/docs/reference/rpc/google.iam.v1#google.iam.v1.TestIamPermissionsRequest
+   */
   /**
    * Test a set of permissions for a resource.
    *

src/index.ts

@@ -109,7 +109,6 @@ export interface Attributes {
   [key: string]: string;
 }
 
-
 export interface SubscriptionCallOptions {
   flowControl?: FlowControlOptions;
   maxConnections?: number;
@@ -120,24 +119,11 @@ export interface SubscriptionCallOptions {
   batching?: BatchPublishOptions;
 }
 
-
-
-/**
- * @callback CreateSnapshotCallback
- * @param {?Error} err Request error, if any.
- * @param {Snapshot} snapshot
- * @param {object} apiResponse The full API response.
- */
 export interface CreateSnapshotCallback {
   (err: Error|null, snapshot?: Snapshot|null,
    apiResponse?: google.pubsub.v1.ISnapshot): void;
 }
 
-/**
- * @typedef {array} CreateSnapshotResponse
- * @property {Snapshot}.
- * @property {object} 1 The full API response.
- */
 export type CreateSnapshotResponse = [Snapshot, google.pubsub.v1.ISnapshot];
 
 /**
@@ -150,30 +136,13 @@ const PROJECT_ID_PLACEHOLDER = '{{projectId}}';
 // tslint:disable-next-line:no-any
 export type Metadata = any;
 
-/**
- * @typedef {array} CreateTopicResponse
- * @property {Topic} 0 The new {@link Topic}.
- * @property {object} 1 The full API response.
- */
 export type CreateTopicResponse = [Topic, google.pubsub.v1.ITopic];
 
-/**
- * @callback CreateTopicCallback
- * @param {?Error} err Request error, if any.
- * @param {Topic} topic The new {@link Topic}.
- * @param {object} apiResponse The full API response.
- */
 export interface CreateTopicCallback {
   (err?: Error|null, topic?: Topic|null,
    apiResponse?: google.pubsub.v1.ITopic): void;
 }
 
-/**
- * @callback CreateSubscriptionCallback
- * @param {?Error} err Request error, if any.
- * @param {Subscription} Subscription
- * @param {object} apiResponse The full API response.
- */
 export interface CreateSubscriptionCallback {
   (err?: Error|null, subscription?: Subscription|null,
    apiResponse?: google.pubsub.v1.ISubscription): void;
@@ -197,11 +166,6 @@ export interface RequestCallback<TResponse> {
   (err?: Error|null, res?: TResponse|null): void;
 }
 
-/**
- * @typedef {array} CreateSubscriptionResponse
- * @property {Subscription} 0 The new {@link Subscription}.
- * @property {object} 1 The full API response.
- */
 export type CreateSubscriptionResponse =
     [Subscription, google.pubsub.v1.ISubscription];
 
@@ -345,6 +309,17 @@ export class PubSub {
   createSubscription(
       topic: Topic|string, name: string,
       callback: CreateSubscriptionCallback): void;
+  /**
+   * @typedef {array} CreateSubscriptionResponse
+   * @property {Subscription} 0 The new {@link Subscription}.
+   * @property {object} 1 The full API response.
+   */
+  /**
+   * @callback CreateSubscriptionCallback
+   * @param {?Error} err Request error, if any.
+   * @param {Subscription} Subscription
+   * @param {object} apiResponse The full API response.
+   */
   /**
    * Options for creating a subscription.
    *
@@ -470,6 +445,17 @@ export class PubSub {
   createTopic(
       name: string, gaxOpts: CallOptions, callback?: CreateTopicCallback): void;
   createTopic(name: string, callback: CreateTopicCallback): void;
+  /**
+   * @typedef {array} CreateTopicResponse
+   * @property {Topic} 0 The new {@link Topic}.
+   * @property {object} 1 The full API response.
+   */
+  /**
+   * @callback CreateTopicCallback
+   * @param {?Error} err Request error, if any.
+   * @param {Topic} topic The new {@link Topic}.
+   * @param {object} apiResponse The full API response.
+   */
   /**
    * Create a topic with the given name.
    *

src/snapshot.ts

@@ -101,6 +101,8 @@ export class Snapshot {
     this.name = Snapshot.formatName_(parent.projectId, name);
   }
 
+  delete(): Promise<google.protobuf.Empty>;
+  delete(callback: RequestCallback<google.protobuf.Empty>): void;
   /**
    * Delete the snapshot.
    *
@@ -120,8 +122,6 @@ export class Snapshot {
    *   const apiResponse = data[0];
    * });
    */
-  delete(): Promise<google.protobuf.Empty>;
-  delete(callback: RequestCallback<google.protobuf.Empty>): void;
   delete(callback?: RequestCallback<google.protobuf.Empty>):
       void|Promise<google.protobuf.Empty> {
     const reqOpts = {
@@ -136,6 +136,7 @@ export class Snapshot {
         },
         callback);
   }
+
   /*@
    * Format the name of a snapshot. A snapshot's full name is in the format of
    * projects/{projectId}/snapshots/{snapshotName}
@@ -146,6 +147,9 @@ export class Snapshot {
     return 'projects/' + projectId + '/snapshots/' + name.split('/').pop();
   }
 
+  create(gaxOpts?: CallOptions): Promise<CreateSnapshotResponse>;
+  create(callback: CreateSnapshotCallback): void;
+  create(gaxOpts: CallOptions, callback: CreateSnapshotCallback): void;
   /**
    * Create a snapshot with the given name.
    *
@@ -181,9 +185,6 @@ export class Snapshot {
    *   const apiResponse = data[1];
    * });
    */
-  create(gaxOpts?: CallOptions): Promise<CreateSnapshotResponse>;
-  create(callback: CreateSnapshotCallback): void;
-  create(gaxOpts: CallOptions, callback: CreateSnapshotCallback): void;
   create(
       gaxOpts?: CallOptions|CreateSnapshotCallback,
       callback?: CreateSnapshotCallback): void|Promise<CreateSnapshotResponse> {
@@ -195,6 +196,9 @@ export class Snapshot {
         .createSnapshot(this.name, gaxOpts! as CallOptions, callback!);
   }
 
+  seek(gaxOpts?: CallOptions): Promise<google.pubsub.v1.ISeekResponse>;
+  seek(callback: SeekCallback): void;
+  seek(gaxOpts: CallOptions, callback: SeekCallback): void;
   /**
    * Seeks an existing subscription to the snapshot.
    *
@@ -220,9 +224,6 @@ export class Snapshot {
    *   const apiResponse = data[0];
    * });
    */
-  seek(gaxOpts?: CallOptions): Promise<google.pubsub.v1.ISeekResponse>;
-  seek(callback: SeekCallback): void;
-  seek(gaxOpts: CallOptions, callback: SeekCallback): void;
   seek(gaxOpts?: CallOptions|SeekCallback, callback?: SeekCallback):
       void|Promise<google.pubsub.v1.ISeekResponse> {
     if (!(this.parent instanceof Subscription)) {