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

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/index-class.ts

@@ -78,9 +78,6 @@ export class Index {
     this.id = id.split('/').pop()!;
   }
 
-  get(gaxOptions?: CallOptions): Promise<GetIndexResponse>;
-  get(callback: GetIndexCallback): void;
-  get(gaxOptions: CallOptions, callback: GetIndexCallback): void;
   /**
    * Get an index if it exists.
    *
@@ -91,6 +88,9 @@ export class Index {
    * @param {Index} callback.index The Index instance.
    * @param {object} callback.apiResponse The full API response.
    */
+  get(gaxOptions?: CallOptions): Promise<GetIndexResponse>;
+  get(callback: GetIndexCallback): void;
+  get(gaxOptions: CallOptions, callback: GetIndexCallback): void;
   get(
     gaxOptionsOrCallback?: CallOptions | GetIndexCallback,
     cb?: GetIndexCallback
@@ -105,12 +105,6 @@ export class Index {
     });
   }
 
-  getMetadata(gaxOptions?: CallOptions): Promise<IndexGetMetadataResponse>;
-  getMetadata(callback: IndexGetMetadataCallback): void;
-  getMetadata(
-    gaxOptions: CallOptions,
-    callback: IndexGetMetadataCallback
-  ): void;
   /**
    * Get the metadata of this index.
    *
@@ -120,6 +114,12 @@ export class Index {
    * @param {?error} callback.err An error returned while making this request.
    * @param {object} callback.metadata The metadata.
    */
+  getMetadata(gaxOptions?: CallOptions): Promise<IndexGetMetadataResponse>;
+  getMetadata(callback: IndexGetMetadataCallback): void;
+  getMetadata(
+    gaxOptions: CallOptions,
+    callback: IndexGetMetadataCallback
+  ): void;
   getMetadata(
     gaxOptionsOrCallback?: CallOptions | IndexGetMetadataCallback,
     cb?: IndexGetMetadataCallback

src/index.ts

@@ -509,8 +509,6 @@ class Datastore extends DatastoreRequest {
     this.auth = new GoogleAuth(this.options);
   }
 
-  export(config: ExportEntitiesConfig): Promise<LongRunningResponse>;
-  export(config: ExportEntitiesConfig, callback: LongRunningCallback): void;
   /**
    * Export entities from this project to a Google Cloud Storage bucket.
    *
@@ -527,6 +525,8 @@ class Datastore extends DatastoreRequest {
    * @param {Operation} callback.operation An operation object that can be used
    *     to check the status of the request.
    */
+  export(config: ExportEntitiesConfig): Promise<LongRunningResponse>;
+  export(config: ExportEntitiesConfig, callback: LongRunningCallback): void;
   export(
     config: ExportEntitiesConfig,
     callback?: LongRunningCallback
@@ -581,9 +581,6 @@ class Datastore extends DatastoreRequest {
     );
   }
 
-  getIndexes(options?: GetIndexesOptions): Promise<GetIndexesResponse>;
-  getIndexes(options: GetIndexesOptions, callback: GetIndexesCallback): void;
-  getIndexes(callback: GetIndexesCallback): void;
   /**
    * Get all of the indexes in this project.
    *
@@ -597,6 +594,9 @@ class Datastore extends DatastoreRequest {
    * @param {object} callback.apiResponse The full API response.
    * @return {void | Promise<GetIndexesResponse>}
    */
+  getIndexes(options?: GetIndexesOptions): Promise<GetIndexesResponse>;
+  getIndexes(options: GetIndexesOptions, callback: GetIndexesCallback): void;
+  getIndexes(callback: GetIndexesCallback): void;
   getIndexes(
     optionsOrCallback?: GetIndexesOptions | GetIndexesCallback,
     cb?: GetIndexesCallback
@@ -687,8 +687,6 @@ class Datastore extends DatastoreRequest {
     return this.auth.getProjectId();
   }
 
-  import(config: ImportEntitiesConfig): Promise<LongRunningResponse>;
-  import(config: ImportEntitiesConfig, callback: LongRunningCallback): void;
   /**
    * Import entities into this project from a remote file.
    *
@@ -705,6 +703,8 @@ class Datastore extends DatastoreRequest {
    * @param {Operation} callback.operation An operation object that can be used
    *     to check the status of the request.
    */
+  import(config: ImportEntitiesConfig): Promise<LongRunningResponse>;
+  import(config: ImportEntitiesConfig, callback: LongRunningCallback): void;
   import(
     config: ImportEntitiesConfig,
     callback?: LongRunningCallback
@@ -769,8 +769,6 @@ class Datastore extends DatastoreRequest {
     return new Index(this, id);
   }
 
-  insert(entities: Entities): Promise<InsertResponse>;
-  insert(entities: Entities, callback: InsertCallback): void;
   /**
    * Maps to {@link Datastore#save}, forcing the method to be `insert`.
    *
@@ -785,6 +783,8 @@ class Datastore extends DatastoreRequest {
    * @param {?error} callback.err An error returned while making this request
    * @param {object} callback.apiResponse The full API response.
    */
+  insert(entities: Entities): Promise<InsertResponse>;
+  insert(entities: Entities, callback: InsertCallback): void;
   insert(
     entities: Entities,
     callback?: InsertCallback
@@ -799,13 +799,6 @@ class Datastore extends DatastoreRequest {
     this.save(entities, callback!);
   }
 
-  save(entities: Entities, gaxOptions?: CallOptions): Promise<SaveResponse>;
-  save(
-    entities: Entities,
-    gaxOptions: CallOptions,
-    callback: SaveCallback
-  ): void;
-  save(entities: Entities, callback: SaveCallback): void;
   /**
    * Insert or update the specified object(s). If a key is incomplete, its
    * associated object is inserted and the original Key object is updated to
@@ -1041,6 +1034,13 @@ class Datastore extends DatastoreRequest {
    * });
    * ```
    */
+  save(entities: Entities, gaxOptions?: CallOptions): Promise<SaveResponse>;
+  save(
+    entities: Entities,
+    gaxOptions: CallOptions,
+    callback: SaveCallback
+  ): void;
+  save(entities: Entities, callback: SaveCallback): void;
   save(
     entities: Entities,
     gaxOptionsOrCallback?: CallOptions | SaveCallback,
@@ -1178,8 +1178,6 @@ class Datastore extends DatastoreRequest {
     );
   }
 
-  update(entities: Entities): Promise<UpdateResponse>;
-  update(entities: Entities, callback: UpdateCallback): void;
   /**
    * Maps to {@link Datastore#save}, forcing the method to be `update`.
    *
@@ -1194,6 +1192,8 @@ class Datastore extends DatastoreRequest {
    * @param {?error} callback.err An error returned while making this request
    * @param {object} callback.apiResponse The full API response.
    */
+  update(entities: Entities): Promise<UpdateResponse>;
+  update(entities: Entities, callback: UpdateCallback): void;
   update(
     entities: Entities,
     callback?: UpdateCallback
@@ -1208,8 +1208,6 @@ class Datastore extends DatastoreRequest {
     this.save(entities, callback!);
   }
 
-  upsert(entities: Entities): Promise<UpsertResponse>;
-  upsert(entities: Entities, callback: UpsertCallback): void;
   /**
    * Maps to {@link Datastore#save}, forcing the method to be `upsert`.
    *
@@ -1224,6 +1222,8 @@ class Datastore extends DatastoreRequest {
    * @param {?error} callback.err An error returned while making this request
    * @param {object} callback.apiResponse The full API response.
    */
+  upsert(entities: Entities): Promise<UpsertResponse>;
+  upsert(entities: Entities, callback: UpsertCallback): void;
   upsert(
     entities: Entities,
     callback?: UpsertCallback
@@ -1450,10 +1450,6 @@ class Datastore extends DatastoreRequest {
   static NO_MORE_RESULTS = 'NO_MORE_RESULTS';
   NO_MORE_RESULTS = Datastore.NO_MORE_RESULTS;
 
-  createQuery(kind?: string): Query;
-  createQuery(kind?: string[]): Query;
-  createQuery(namespace: string, kind: string): Query;
-  createQuery(namespace: string, kind: string[]): Query;
   /**
    * Create a query for the specified kind. See {@link Query} for all
    * of the available methods.
@@ -1472,6 +1468,10 @@ class Datastore extends DatastoreRequest {
    * const query = datastore.createQuery('Company');
    * ```
    */
+  createQuery(kind?: string): Query;
+  createQuery(kind?: string[]): Query;
+  createQuery(namespace: string, kind: string): Query;
+  createQuery(namespace: string, kind: string[]): Query;
   createQuery(
     namespaceOrKind?: string | string[],
     kind?: string | string[]
@@ -1484,9 +1484,6 @@ class Datastore extends DatastoreRequest {
     return new Query(this, namespace, arrify(kind) as string[]);
   }
 
-  key(options: entity.KeyOptions): entity.Key;
-  key(path: PathType[]): entity.Key;
-  key(path: string): entity.Key;
   /**
    * Helper to create a Key object, scoped to the instance's namespace by
    * default.
@@ -1567,6 +1564,9 @@ class Datastore extends DatastoreRequest {
    * const key = datastore.key(['Company', 'Google', 'Employee']);
    * ```
    */
+  key(options: entity.KeyOptions): entity.Key;
+  key(path: PathType[]): entity.Key;
+  key(path: string): entity.Key;
   key(options: string | entity.KeyOptions | PathType[]): entity.Key {
     const keyOptions = is.object(options)
       ? (options as entity.KeyOptions)
@@ -1598,16 +1598,6 @@ class Datastore extends DatastoreRequest {
     return Datastore.isKey(value);
   }
 
-  keyToLegacyUrlSafe(key: entity.Key, locationPrefix?: string): Promise<string>;
-  keyToLegacyUrlSafe(
-    key: entity.Key,
-    callback: KeyToLegacyUrlSafeCallback
-  ): void;
-  keyToLegacyUrlSafe(
-    key: entity.Key,
-    locationPrefix: string,
-    callback: KeyToLegacyUrlSafeCallback
-  ): void;
   /**
    * Helper to create a URL safe key.
    *
@@ -1660,6 +1650,16 @@ class Datastore extends DatastoreRequest {
    * });
    * ```
    */
+  keyToLegacyUrlSafe(key: entity.Key, locationPrefix?: string): Promise<string>;
+  keyToLegacyUrlSafe(
+    key: entity.Key,
+    callback: KeyToLegacyUrlSafeCallback
+  ): void;
+  keyToLegacyUrlSafe(
+    key: entity.Key,
+    locationPrefix: string,
+    callback: KeyToLegacyUrlSafeCallback
+  ): void;
   keyToLegacyUrlSafe(
     key: entity.Key,
     locationPrefixOrCallback?: string | KeyToLegacyUrlSafeCallback,

src/query.ts

@@ -152,8 +152,6 @@ class Query {
     this.offsetVal = -1;
   }
 
-  filter(property: string, value: {}): Query;
-  filter(property: string, operator: Operator, value: {}): Query;
   /**
    * Datastore allows querying on properties. Supported comparison operators
    * are `=`, `<`, `>`, `<=`, and `>=`. "Not equal" and `IN` operators are
@@ -194,6 +192,8 @@ class Query {
    * const keyQuery = query.filter('__key__', key);
    * ```
    */
+  filter(property: string, value: {}): Query;
+  filter(property: string, operator: Operator, value: {}): Query;
   filter(property: string, operatorOrValue: Operator, value?: {}): Query {
     let operator = operatorOrValue as Operator;
     if (arguments.length === 2) {
@@ -407,9 +407,6 @@ class Query {
     return this;
   }
 
-  run(options?: RunQueryOptions): Promise<RunQueryResponse>;
-  run(options: RunQueryOptions, callback: RunQueryCallback): void;
-  run(callback: RunQueryCallback): void;
   /**
    * Run the query.
    *
@@ -475,6 +472,9 @@ class Query {
    * });
    * ```
    */
+  run(options?: RunQueryOptions): Promise<RunQueryResponse>;
+  run(options: RunQueryOptions, callback: RunQueryCallback): void;
+  run(callback: RunQueryCallback): void;
   run(
     optionsOrCallback?: RunQueryOptions | RunQueryCallback,
     cb?: RunQueryCallback