[Cosmos] TSDoc compliance (#13849)

sdk/cosmosdb/cosmos/consumer-test.js

@@ -1,6 +1,6 @@
 const execa = require("execa");
 
-let versions = ["3.1", "3.9"];
+let versions = ["3.9"];
 
 if (!process.env.SKIP_LATEST) {
   versions.push("latest");
@@ -17,11 +17,11 @@ async function exec(cmd) {
   try {
     console.log("Running typescript consumer test against", versions);
     for (const version of versions) {
-      console.log(`Compling with typescript@${version} - Basic`);
+      console.log(`Compiling with typescript@${version} - Basic`);
       await exec(
         `npx -p typescript@${version} tsc ./test.ts --allowSyntheticDefaultImports true --target ES5`
       );
-      console.log(`Compling with typescript@${version} - Custom lib`);
+      console.log(`Compiling with typescript@${version} - Custom lib`);
       await exec(
         `npx -p typescript@${version} tsc ./test.ts --allowSyntheticDefaultImports true --lib es2018`
       );

sdk/cosmosdb/cosmos/review/cosmos.api.md

@@ -723,7 +723,6 @@ export class GlobalEndpointManager {
     constructor(options: CosmosClientOptions, readDatabaseAccount: (opts: RequestOptions) => Promise<ResourceResponse<DatabaseAccount>>);
     // (undocumented)
     canUseMultipleWriteLocations(resourceType?: ResourceType, operationType?: OperationType): boolean;
-    // (undocumented)
     enableEndpointDiscovery: boolean;
     getReadEndpoint(): Promise<string>;
     // (undocumented)

sdk/cosmosdb/cosmos/src/ChangeFeedIterator.ts

@@ -23,13 +23,6 @@ export class ChangeFeedIterator<T> {
 
   /**
    * @internal
-   * @hidden
-   *
-   * @param clientContext
-   * @param resourceId
-   * @param resourceLink
-   * @param isPartitionedContainer
-   * @param changeFeedOptions
    */
   constructor(
     private clientContext: ClientContext,

sdk/cosmosdb/cosmos/src/ChangeFeedResponse.ts

@@ -9,12 +9,6 @@ import { CosmosHeaders } from "./queryExecutionContext";
 export class ChangeFeedResponse<T> {
   /**
    * @internal
-   * @hidden
-   *
-   * @param result
-   * @param count
-   * @param statusCode
-   * @param headers
    */
   constructor(
     /**

sdk/cosmosdb/cosmos/src/ClientContext.ts

@@ -505,7 +505,7 @@ export class ClientContext {
 
   /**
    * Gets the Database account information.
-   * @param {string} [options.urlConnection]   - The endpoint url whose database account needs to be retrieved. \
+   * @param options - `urlConnection` in the options is the endpoint url whose database account needs to be retrieved.
    * If not present, current client's url will be used.
    */
   public async getDatabaseAccount(

sdk/cosmosdb/cosmos/src/CosmosClient.ts

@@ -56,7 +56,7 @@ export class CosmosClient {
   constructor(connectionString: string);
   /**
    * Creates a new {@link CosmosClient} object. See {@link CosmosClientOptions} for more details on what options you can use.
-   * @param options bag of options - require at least endpoint and auth to be configured
+   * @param options - bag of options; require at least endpoint and auth to be configured
    */
   constructor(options: CosmosClientOptions); // tslint:disable-line:unified-signatures
   constructor(optionsOrConnectionString: string | CosmosClientOptions) {
@@ -131,7 +131,7 @@ export class CosmosClient {
    *
    * This does not make a network call. Use `.read` to get info about the database after getting the {@link Database} object.
    *
-   * @param id The id of the database.
+   * @param id - The id of the database.
    * @example Create a new container off of an existing database
    * ```typescript
    * const container = client.database("<database id>").containers.create("<container id>");
@@ -148,7 +148,7 @@ export class CosmosClient {
 
   /**
    * Used for reading, or updating a existing offer by id.
-   * @param id The id of the offer.
+   * @param id - The id of the offer.
    */
   public offer(id: string) {
     return new Offer(this, id, this.clientContext);

sdk/cosmosdb/cosmos/src/CosmosClientOptions.ts

@@ -29,8 +29,8 @@ export interface CosmosClientOptions {
    * Allows users to generating their own auth tokens, potentially using a separate service
    */
   tokenProvider?: TokenProvider;
-  /** AAD token from @azure/identity
-   * Obtain a credential object by creating an @azure/identity credential object
+  /** AAD token from `@azure/identity`
+   * Obtain a credential object by creating an `@azure/identity` credential object
    * We will then use your credential object and a scope URL (your cosmos db endpoint)
    * to authenticate requests to Cosmos
    * This feature is in private preview and not yet available for every Cosmos account

sdk/cosmosdb/cosmos/src/auth.ts

@@ -24,12 +24,6 @@ export type TokenProvider = (requestInfo: RequestInfo) => Promise<string>;
 
 /**
  * @hidden
- * @param clientOptions
- * @param verb
- * @param path
- * @param resourceId
- * @param resourceType
- * @param headers
  */
 export async function setAuthorizationHeader(
   clientOptions: CosmosClientOptions,
@@ -102,9 +96,6 @@ export async function setAuthorizationTokenHeaderUsingMasterKey(
 
 /**
  * @hidden
- * @param resourceTokens
- * @param path
- * @param resourceId
  */
 // TODO: Resource tokens
 export function getAuthorizationTokenUsingResourceTokens(

sdk/cosmosdb/cosmos/src/client/Conflict/Conflict.ts

@@ -21,8 +21,8 @@ export class Conflict {
   }
   /**
    * @hidden
-   * @param container The parent {@link Container}.
-   * @param id The id of the given {@link Conflict}.
+   * @param container - The parent {@link Container}.
+   * @param id - The id of the given {@link Conflict}.
    */
   constructor(
     public readonly container: Container,
@@ -32,7 +32,6 @@ export class Conflict {
 
   /**
    * Read the {@link ConflictDefinition} for the given {@link Conflict}.
-   * @param options
    */
   public async read(options?: RequestOptions): Promise<ConflictResponse> {
     const path = getPathFromLink(this.url, ResourceType.conflicts);
@@ -49,7 +48,6 @@ export class Conflict {
 
   /**
    * Delete the given {@link ConflictDefinition}.
-   * @param options
    */
   public async delete(options?: RequestOptions): Promise<ConflictResponse> {
     const path = getPathFromLink(this.url);

sdk/cosmosdb/cosmos/src/client/Conflict/Conflicts.ts

@@ -22,15 +22,15 @@ export class Conflicts {
 
   /**
    * Queries all conflicts.
-   * @param query Query configuration for the operation. See {@link SqlQuerySpec} for more info on how to configure a query.
-   * @param options Use to set options like response page size, continuation tokens, etc.
+   * @param query - Query configuration for the operation. See {@link SqlQuerySpec} for more info on how to configure a query.
+   * @param options - Use to set options like response page size, continuation tokens, etc.
    * @returns {@link QueryIterator} Allows you to return results in an array or iterate over them one at a time.
    */
   public query(query: string | SqlQuerySpec, options?: FeedOptions): QueryIterator<any>;
   /**
    * Queries all conflicts.
-   * @param query Query configuration for the operation. See {@link SqlQuerySpec} for more info on how to configure a query.
-   * @param options Use to set options like response page size, continuation tokens, etc.
+   * @param query - Query configuration for the operation. See {@link SqlQuerySpec} for more info on how to configure a query.
+   * @param options - Use to set options like response page size, continuation tokens, etc.
    * @returns {@link QueryIterator} Allows you to return results in an array or iterate over them one at a time.
    */
   public query<T>(query: string | SqlQuerySpec, options?: FeedOptions): QueryIterator<T>;
@@ -52,7 +52,7 @@ export class Conflicts {
 
   /**
    * Reads all conflicts
-   * @param options Use to set options like response page size, continuation tokens, etc.
+   * @param options - Use to set options like response page size, continuation tokens, etc.
    */
   public readAll(options?: FeedOptions): QueryIterator<ConflictDefinition & Resource> {
     return this.query<ConflictDefinition & Resource>(undefined, options);

sdk/cosmosdb/cosmos/src/client/Container/Container.ts

@@ -86,8 +86,8 @@ export class Container {
 
   /**
    * Returns a container instance. Note: You should get this from `database.container(id)`, rather than creating your own object.
-   * @param database The parent {@link Database}.
-   * @param id The id of the given container.
+   * @param database - The parent {@link Database}.
+   * @param id - The id of the given container.
    * @hidden
    */
   constructor(
@@ -101,10 +101,10 @@ export class Container {
    *
    * Use `.items` for creating new items, or querying/reading all items.
    *
-   * @param id The id of the {@link Item}.
-   * @param partitionKeyValue The value of the {@link Item} partition key
+   * @param id - The id of the {@link Item}.
+   * @param partitionKeyValue - The value of the {@link Item} partition key
    * @example Replace an item
-   * const {body: replacedItem} = await container.item("<item id>", "<partition key value>").replace({id: "<item id>", title: "Updated post", authorID: 5});
+   * `const {body: replacedItem} = await container.item("<item id>", "<partition key value>").replace({id: "<item id>", title: "Updated post", authorID: 5});`
    */
   public item(id: string, partitionKeyValue?: any): Item {
     return new Item(this, id, partitionKeyValue, this.clientContext);
@@ -114,7 +114,7 @@ export class Container {
    * Used to read, replace, or delete a specific, existing {@link Conflict} by id.
    *
    * Use `.conflicts` for creating new conflicts, or querying/reading all conflicts.
-   * @param id The id of the {@link Conflict}.
+   * @param id - The id of the {@link Conflict}.
    */
   public conflict(id: string): Conflict {
     return new Conflict(this, id, this.clientContext);
@@ -175,9 +175,6 @@ export class Container {
   /**
    * Gets the partition key definition first by looking into the cache otherwise by reading the collection.
    * @deprecated This method has been renamed to readPartitionKeyDefinition.
-   * @param {string} collectionLink   - Link to the collection whose partition key needs to be extracted.
-   * @param {function} callback       - \
-   * The arguments to the callback are(in order): error, partitionKeyDefinition, response object and response headers
    */
   public async getPartitionKeyDefinition(): Promise<ResourceResponse<PartitionKeyDefinition>> {
     return this.readPartitionKeyDefinition();
@@ -186,9 +183,6 @@ export class Container {
   /**
    * Gets the partition key definition first by looking into the cache otherwise by reading the collection.
    * @hidden
-   * @param {string} collectionLink   - Link to the collection whose partition key needs to be extracted.
-   * @param {function} callback       - \
-   * The arguments to the callback are(in order): error, partitionKeyDefinition, response object and response headers
    */
   public async readPartitionKeyDefinition(): Promise<ResourceResponse<PartitionKeyDefinition>> {
     // $ISSUE-felixfan-2016-03-17: Make name based path and link based path use the same key
@@ -211,7 +205,6 @@ export class Container {
 
   /**
    * Gets offer on container. If none exists, returns an OfferResponse with undefined.
-   * @param options
    */
   public async readOffer(options: RequestOptions = {}): Promise<OfferResponse> {
     const { resource: container } = await this.read();

sdk/cosmosdb/cosmos/src/client/Container/Containers.ts

@@ -36,8 +36,8 @@ export class Containers {
 
   /**
    * Queries all containers.
-   * @param query Query configuration for the operation. See {@link SqlQuerySpec} for more info on how to configure a query.
-   * @param options Use to set options like response page size, continuation tokens, etc.
+   * @param query - Query configuration for the operation. See {@link SqlQuerySpec} for more info on how to configure a query.
+   * @param options - Use to set options like response page size, continuation tokens, etc.
    * @returns {@link QueryIterator} Allows you to return specific containers in an array or iterate over them one at a time.
    * @example Read all containers to array.
    * ```typescript
@@ -53,8 +53,8 @@ export class Containers {
   public query(query: SqlQuerySpec, options?: FeedOptions): QueryIterator<any>;
   /**
    * Queries all containers.
-   * @param query Query configuration for the operation. See {@link SqlQuerySpec} for more info on how to configure a query.
-   * @param options Use to set options like response page size, continuation tokens, etc.
+   * @param query - Query configuration for the operation. See {@link SqlQuerySpec} for more info on how to configure a query.
+   * @param options - Use to set options like response page size, continuation tokens, etc.
    * @returns {@link QueryIterator} Allows you to return specific containers in an array or iterate over them one at a time.
    * @example Read all containers to array.
    * ```typescript
@@ -98,8 +98,8 @@ export class Containers {
    * Since containers are application resources, they can be authorized using either the
    * master key or resource keys.
    *
-   * @param body Represents the body of the container.
-   * @param options Use to set options like response page size, continuation tokens, etc.
+   * @param body - Represents the body of the container.
+   * @param options - Use to set options like response page size, continuation tokens, etc.
    */
   public async create(
     body: ContainerRequest,
@@ -182,8 +182,8 @@ export class Containers {
    * Since containers are application resources, they can be authorized using either the
    * master key or resource keys.
    *
-   * @param body Represents the body of the container.
-   * @param options Use to set options like response page size, continuation tokens, etc.
+   * @param body - Represents the body of the container.
+   * @param options - Use to set options like response page size, continuation tokens, etc.
    */
   public async createIfNotExists(
     body: ContainerRequest,
@@ -213,7 +213,7 @@ export class Containers {
 
   /**
    * Read all containers.
-   * @param options Use to set options like response page size, continuation tokens, etc.
+   * @param options - Use to set options like response page size, continuation tokens, etc.
    * @returns {@link QueryIterator} Allows you to return all containers in an array or iterate over them one at a time.
    * @example Read all containers to array.
    * ```typescript

sdk/cosmosdb/cosmos/src/client/Database/Database.ts

@@ -111,7 +111,6 @@ export class Database {
 
   /**
    * Gets offer on database. If none exists, returns an OfferResponse with undefined.
-   * @param options
    */
   public async readOffer(options: RequestOptions = {}): Promise<OfferResponse> {
     const { resource: record } = await this.read();

sdk/cosmosdb/cosmos/src/client/Database/Databases.ts

@@ -26,7 +26,7 @@ import { validateOffer } from "../../utils/offers";
 export class Databases {
   /**
    * @hidden
-   * @param client The parent {@link CosmosClient} for the Database.
+   * @param client - The parent {@link CosmosClient} for the Database.
    */
   constructor(
     public readonly client: CosmosClient,
@@ -35,8 +35,8 @@ export class Databases {
 
   /**
    * Queries all databases.
-   * @param query Query configuration for the operation. See {@link SqlQuerySpec} for more info on how to configure a query.
-   * @param options Use to set options like response page size, continuation tokens, etc.
+   * @param query - Query configuration for the operation. See {@link SqlQuerySpec} for more info on how to configure a query.
+   * @param options - Use to set options like response page size, continuation tokens, etc.
    * @returns {@link QueryIterator} Allows you to return all databases in an array or iterate over them one at a time.
    * @example Read all databases to array.
    * ```typescript
@@ -52,8 +52,8 @@ export class Databases {
   public query(query: string | SqlQuerySpec, options?: FeedOptions): QueryIterator<any>;
   /**
    * Queries all databases.
-   * @param query Query configuration for the operation. See {@link SqlQuerySpec} for more info on how to configure a query.
-   * @param options Use to set options like response page size, continuation tokens, etc.
+   * @param query - Query configuration for the operation. See {@link SqlQuerySpec} for more info on how to configure a query.
+   * @param options - Use to set options like response page size, continuation tokens, etc.
    * @returns {@link QueryIterator} Allows you to return all databases in an array or iterate over them one at a time.
    * @example Read all databases to array.
    * ```typescript
@@ -92,8 +92,8 @@ export class Databases {
    * documents. Since databases are an administrative resource, the Service Master Key will be
    * required in order to access and successfully complete any action using the User APIs.
    *
-   * @param body The {@link DatabaseDefinition} that represents the {@link Database} to be created.
-   * @param options Use to set options like response page size, continuation tokens, etc.
+   * @param body - The {@link DatabaseDefinition} that represents the {@link Database} to be created.
+   * @param options - Use to set options like response page size, continuation tokens, etc.
    */
   public async create(
     body: DatabaseRequest,
@@ -155,8 +155,8 @@ export class Databases {
    * documents. Since databases are an an administrative resource, the Service Master Key will be
    * required in order to access and successfully complete any action using the User APIs.
    *
-   * @param body The {@link DatabaseDefinition} that represents the {@link Database} to be created.
-   * @param options
+   * @param body - The {@link DatabaseDefinition} that represents the {@link Database} to be created.
+   * @param options - Additional options for the request
    */
   public async createIfNotExists(
     body: DatabaseRequest,
@@ -187,7 +187,7 @@ export class Databases {
   // TODO: DatabaseResponse for QueryIterator?
   /**
    * Reads all databases.
-   * @param options Use to set options like response page size, continuation tokens, etc.
+   * @param options - Use to set options like response page size, continuation tokens, etc.
    * @returns {@link QueryIterator} Allows you to return all databases in an array or iterate over them one at a time.
    * @example Read all databases to array.
    * ```typescript