From 78db83fe148b8dad1fe8db4112cf92b45ffb13d3 Mon Sep 17 00:00:00 2001 From: Deyaaeldeen Almahallawi Date: Wed, 16 Dec 2020 21:01:34 -0500 Subject: [PATCH] Standardization of our documentation comments (#12912) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit # Status quo Some of our documentation comments are [TypeDoc](http://typedoc.org/guides/doccomments/) and some of them are JSDoc with type description in the comments even though it is for typed TS code. # Standardization I decided the best way to go about this is to migrate to [TSDoc](https://github.com/Microsoft/tsdoc) and enforcing it using the [tsdoc eslint plugin](https://www.npmjs.com/package/eslint-plugin-tsdoc). Pros: - TSDoc is a proposal to standardize the doc comments used in TypeScript code, so that different tools can extract content without getting confused by each other’s markup. - It is being developed at Microsoft, with the TypeScript team. - It has an ESLint plugin that enforces it and will error when it sees unsupported tags (e.g. `@memberof`, `@class`, `@constructor`, `@type`, etc). Cons: - It is still in early stages (adoption is ongoing though, e.g. it is being used by the API extractor tool). - TSDoc != TypeDoc (the tool we currently use for generating our documentation). However, TypeDoc plans to officially support TSDoc in v1.1 (see https://github.com/TypeStrong/typedoc/issues/1266). # Notable tag changes - `@ignore` is a JSDoc tag and was used in conjunction with `@internal`. These tags were needed because [TypeDoc does not yet support documenting only definitions exported by the entry point](https://github.com/TypeStrong/typedoc/pull/1184#issuecomment-650809143) and still documents everything exported from all files. I removed `@ignore` because [`@internal`](https://tsdoc.org/pages/tags/internal) only should suffice - `@ignore` when used alone is replaced with TypeDoc's [`hidden`](http://typedoc.org/guides/doccomments/#hidden-and-ignore). EDIT: I replaced `@ignore` with [`@hidden`](https://github.com/TypeStrong/typedoc/releases/tag/v0.12.0) because the TypeDoc version used for `docs.microsoft.com` is v0.15.0 which does not support `--stripInternal`. After, they upgrade, I will remove all `@hidden` tags. - `@summary` is gone because it is not part of TSDoc or TypeDoc This PR applies the changes to packages that respect our linting rules. Ones that do not yet will be migrated later when we start fixing their linting issues. Here are vanilla examples of TypeDoc 0.18.0 (version used by our EngSys) after the changes here as a sanity check: - random method: ![typedoc](https://user-images.githubusercontent.com/6074665/102302881-f6186380-3f27-11eb-8cc6-93e4c8f7d42d.PNG) - a class constructor that used to have type information in the documentation comments: ![constructor](https://user-images.githubusercontent.com/6074665/102357078-f8a4a880-3f7b-11eb-92d1-c086ecc39c0b.PNG) # `@hidden` works the same way as `@ignore` Here are the list of documented functions generated by `TypeDoc v0.15.0` for the text analytics package and there is no function that was marked `@hidden`, e.g. `combineSuccessfulAndErroneousDocumentsWithStatisticsAndModelVersion` ![image](https://user-images.githubusercontent.com/6074665/102426196-e018aa80-3fdc-11eb-8b69-1ac265391fad.png) # Things to consider - Our documentation must be generated using the TypeDoc flag [`--stripInternal`](http://typedoc.org/guides/options/#stripinternal) - Should we add a `docs` npm script to our `package.json`s (similar to [Cosmos's](https://github.com/Azure/azure-sdk-for-js/blob/2424b74f029273677f62433f28dd1390806f682c/sdk/cosmosdb/cosmos/package.json#L60)) so that we can see how our docs are generated as we write our comments? Fixes https://github.com/Azure/azure-sdk-for-js/issues/3027. --- common/config/rush/pnpm-lock.yaml | 25 ++- .../eslint-plugin-azure-sdk/package.json | 3 +- .../src/configs/azure-sdk-base.ts | 5 +- eng/tools/generate-doc/index.js | 1 + .../src/AnomalyDetectorClient.ts | 20 +- .../ai-anomaly-detector/src/logger.ts | 2 +- .../ai-anomaly-detector/src/models.ts | 4 +- .../ai-anomaly-detector/src/tracing.ts | 7 +- .../ai-anomaly-detector/tsdoc.json | 4 + .../abort-controller/src/AbortController.ts | 33 ++- sdk/core/abort-controller/src/AbortSignal.ts | 25 +-- sdk/core/core-auth/src/azureKeyCredential.ts | 4 +- sdk/core/core-auth/src/tokenCredential.ts | 6 +- sdk/core/core-http/src/createSpan.ts | 6 +- .../src/credentials/accessTokenCache.ts | 2 +- .../src/credentials/accessTokenRefresher.ts | 6 +- .../src/credentials/apiKeyCredentials.ts | 8 +- .../basicAuthenticationCredentials.ts | 11 +- .../credentials/serviceClientCredentials.ts | 4 +- .../src/credentials/topicCredentials.ts | 3 +- sdk/core/core-http/src/httpHeaders.ts | 16 +- sdk/core/core-http/src/httpPipelineLogger.ts | 10 +- sdk/core/core-http/src/operationOptions.ts | 5 +- sdk/core/core-http/src/operationParameter.ts | 2 +- .../bearerTokenAuthenticationPolicy.ts | 16 +- .../disableResponseDecompressionPolicy.ts | 8 +- .../src/policies/exponentialRetryPolicy.ts | 15 +- .../core-http/src/policies/keepAlivePolicy.ts | 11 +- .../core-http/src/policies/ndJsonPolicy.ts | 6 +- .../core-http/src/policies/requestPolicy.ts | 18 +- .../src/policies/rpRegistrationPolicy.ts | 32 +-- .../src/policies/systemErrorRetryPolicy.ts | 12 +- sdk/core/core-http/src/serializer.ts | 44 ++-- sdk/core/core-http/src/serviceClient.ts | 14 +- sdk/core/core-http/src/util/base64.browser.ts | 6 +- sdk/core/core-http/src/util/base64.ts | 6 +- sdk/core/core-http/src/util/constants.ts | 32 --- .../src/util/exponentialBackoffStrategy.ts | 14 +- sdk/core/core-http/src/util/utils.ts | 75 ++++--- sdk/core/core-http/src/util/xml.ts | 10 +- sdk/core/core-http/src/webResource.ts | 19 +- .../test/data/TestClient/src/testClient.ts | 16 +- sdk/core/core-http/test/msAssert.ts | 8 +- sdk/core/core-http/tsdoc.json | 4 + sdk/core/core-lro/src/pollOperation.ts | 8 +- sdk/core/core-lro/src/poller.ts | 28 +-- sdk/core/core-lro/tsdoc.json | 4 + sdk/core/core-tracing/src/tracerProxy.ts | 2 +- .../core-tracing/src/tracers/noop/noOpSpan.ts | 16 +- .../src/tracers/noop/noOpTracer.ts | 12 +- .../opencensus/openCensusSpanWrapper.ts | 24 +-- .../opencensus/openCensusTraceStateWrapper.ts | 2 +- .../opencensus/openCensusTracerWrapper.ts | 14 +- .../core-tracing/src/tracers/test/testSpan.ts | 22 +- .../src/tracers/test/testTracer.ts | 6 +- .../src/utils/traceParentHeader.ts | 4 +- sdk/core/core-tracing/tsdoc.json | 4 + sdk/core/logger/src/index.ts | 6 +- sdk/core/logger/tsdoc.json | 4 + sdk/eventgrid/eventgrid/src/consumer.ts | 8 +- .../eventgrid/src/cryptoHelpers.browser.ts | 2 +- sdk/eventgrid/eventgrid/src/cryptoHelpers.ts | 2 +- .../eventgrid/src/eventGridClient.ts | 14 +- .../src/generateSharedAccessSignature.ts | 8 +- sdk/eventgrid/eventgrid/src/logger.ts | 2 +- sdk/eventgrid/eventgrid/src/predicates.ts | 12 +- .../src/sharedAccessSignitureCredential.ts | 4 +- sdk/eventgrid/eventgrid/src/tracing.ts | 7 +- sdk/eventgrid/eventgrid/src/util.ts | 4 +- sdk/eventgrid/eventgrid/tsdoc.json | 4 + .../src/formRecognizerClient.ts | 84 ++++---- .../src/formTrainingClient.ts | 54 ++--- .../ai-form-recognizer/src/logger.ts | 2 +- .../src/lro/analyze/contentPoller.ts | 3 +- .../ai-form-recognizer/src/lro/copy/poller.ts | 3 +- .../src/lro/train/poller.ts | 3 +- .../ai-form-recognizer/src/models.ts | 2 +- .../ai-form-recognizer/src/tracing.ts | 7 +- .../src/utils/utils.node.ts | 7 +- .../ai-form-recognizer/test/utils/matrix.ts | 8 +- .../ai-form-recognizer/tsdoc.json | 4 + sdk/identity/identity/src/client/errors.ts | 2 +- .../identity/src/client/msalClient.ts | 8 +- sdk/identity/identity/src/constants.ts | 4 +- .../authorizationCodeCredential.ts | 28 +-- .../src/credentials/azureCliCredential.ts | 6 +- .../src/credentials/chainedTokenCredential.ts | 6 +- .../clientCertificateCredential.ts | 12 +- .../src/credentials/clientSecretCredential.ts | 12 +- .../defaultAzureCredential.browser.ts | 2 +- .../src/credentials/defaultAzureCredential.ts | 2 +- .../src/credentials/deviceCodeCredential.ts | 20 +- .../src/credentials/environmentCredential.ts | 6 +- .../interactiveBrowserCredential.browser.ts | 12 +- .../interactiveBrowserCredential.ts | 6 +- .../managedIdentityCredential/index.ts | 12 +- .../credentials/usernamePasswordCredential.ts | 14 +- .../credentials/visualStudioCodeCredential.ts | 6 +- sdk/identity/identity/src/util/logging.ts | 12 +- sdk/identity/identity/src/util/tracing.ts | 4 +- .../test/mockAzureCliCredentialClient.ts | 2 +- sdk/identity/identity/tsdoc.json | 4 + .../keyvault-admin/src/accessControlClient.ts | 76 +++---- .../keyvault-admin/src/backupClient.ts | 38 ++-- sdk/keyvault/keyvault-admin/src/log.ts | 2 +- .../src/lro/keyVaultAdminPoller.ts | 1 - sdk/keyvault/keyvault-admin/tsdoc.json | 4 + .../src/certificatesModels.ts | 5 +- .../keyvault-certificates/src/identifier.ts | 6 +- .../keyvault-certificates/src/index.ts | 175 ++++++++-------- sdk/keyvault/keyvault-certificates/src/log.ts | 2 +- .../keyvault-certificates/src/utils.ts | 12 +- .../test/utils/lro/restore/operation.ts | 14 +- .../test/utils/lro/restore/poller.ts | 2 - sdk/keyvault/keyvault-certificates/tsdoc.json | 4 + .../src/challengeBasedAuthenticationPolicy.ts | 20 +- sdk/keyvault/keyvault-common/src/tracing.ts | 8 +- .../keyvault-keys/src/cryptographyClient.ts | 77 ++++--- .../src/cryptographyClientModels.ts | 3 - sdk/keyvault/keyvault-keys/src/identifier.ts | 7 +- sdk/keyvault/keyvault-keys/src/index.ts | 137 ++++++------ sdk/keyvault/keyvault-keys/src/keysModels.ts | 10 +- .../localCryptography/algorithms.browser.ts | 4 +- .../src/localCryptography/algorithms.ts | 8 +- .../src/localCryptography/conversions.ts | 6 +- .../src/localCryptography/hash.browser.ts | 2 +- .../src/localCryptography/hash.ts | 2 +- .../src/localCryptography/models.ts | 16 +- .../src/localCryptographyClient.ts | 21 +- sdk/keyvault/keyvault-keys/src/log.ts | 2 +- .../keyvault-keys/src/transformations.ts | 2 +- .../test/utils/lro/restore/operation.ts | 14 +- .../test/utils/lro/restore/poller.ts | 2 - sdk/keyvault/keyvault-keys/tsdoc.json | 4 + .../keyvault-secrets/src/identifier.ts | 6 +- sdk/keyvault/keyvault-secrets/src/index.ts | 115 +++++------ sdk/keyvault/keyvault-secrets/src/log.ts | 2 +- .../src/lro/keyVaultSecretPoller.ts | 10 +- .../keyvault-secrets/src/secretsModels.ts | 6 +- .../keyvault-secrets/src/transformations.ts | 2 +- .../test/utils/lro/restore/operation.ts | 14 +- .../test/utils/lro/restore/poller.ts | 2 - sdk/keyvault/keyvault-secrets/tsdoc.json | 4 + .../ai-metrics-advisor/src/logger.ts | 2 +- .../src/metricsAdvisorAdministrationClient.ts | 172 +++++++-------- .../src/metricsAdvisorClient.ts | 195 +++++++++--------- .../src/metricsAdvisorKeyCredentialPolicy.ts | 4 +- .../ai-metrics-advisor/src/models.ts | 4 +- .../ai-metrics-advisor/src/tracing.ts | 7 +- .../ai-metrics-advisor/tsdoc.json | 4 + .../schema-registry/src/logger.ts | 2 +- .../schema-registry/src/models.ts | 12 +- .../src/schemaRegistryClient.ts | 20 +- sdk/tables/data-tables/src/TableBatch.ts | 33 ++- sdk/tables/data-tables/src/TableClient.ts | 82 ++++---- .../data-tables/src/TableServiceClient.ts | 62 +++--- .../src/TablesSharedKeyCredential.browser.ts | 4 +- .../src/TablesSharedKeyCredential.ts | 23 +-- .../src/TablesSharedKeyCredentialPolicy.ts | 21 +- sdk/tables/data-tables/src/logger.ts | 2 +- sdk/tables/data-tables/src/models.ts | 16 +- .../utils/accountConnectionString.browser.ts | 4 +- .../src/utils/accountConnectionString.ts | 4 +- .../src/utils/bufferSerializer.browser.ts | 4 +- .../data-tables/src/utils/bufferSerializer.ts | 4 +- .../data-tables/src/utils/connectionString.ts | 13 +- .../data-tables/src/utils/internalModels.ts | 50 ++--- sdk/tables/data-tables/src/utils/tracing.ts | 7 +- sdk/tables/data-tables/tsdoc.json | 4 + .../ai-text-analytics/src/logger.ts | 2 +- .../ai-text-analytics/src/lro/poller.ts | 10 +- .../src/textAnalyticsClient.ts | 159 +++++++------- .../src/textAnalyticsResult.ts | 20 +- .../ai-text-analytics/src/tracing.ts | 7 +- .../ai-text-analytics/src/util.ts | 11 +- .../ai-text-analytics/tsdoc.json | 4 + tsdoc.json | 9 + 177 files changed, 1492 insertions(+), 1490 deletions(-) create mode 100644 sdk/anomalydetector/ai-anomaly-detector/tsdoc.json create mode 100644 sdk/core/core-http/tsdoc.json create mode 100644 sdk/core/core-lro/tsdoc.json create mode 100644 sdk/core/core-tracing/tsdoc.json create mode 100644 sdk/core/logger/tsdoc.json create mode 100644 sdk/eventgrid/eventgrid/tsdoc.json create mode 100644 sdk/formrecognizer/ai-form-recognizer/tsdoc.json create mode 100644 sdk/identity/identity/tsdoc.json create mode 100644 sdk/keyvault/keyvault-admin/tsdoc.json create mode 100644 sdk/keyvault/keyvault-certificates/tsdoc.json create mode 100644 sdk/keyvault/keyvault-keys/tsdoc.json create mode 100644 sdk/keyvault/keyvault-secrets/tsdoc.json create mode 100644 sdk/metricsadvisor/ai-metrics-advisor/tsdoc.json create mode 100644 sdk/tables/data-tables/tsdoc.json create mode 100644 sdk/textanalytics/ai-text-analytics/tsdoc.json create mode 100644 tsdoc.json diff --git a/common/config/rush/pnpm-lock.yaml b/common/config/rush/pnpm-lock.yaml index e887e9d4b967..8ef1fd445776 100644 --- a/common/config/rush/pnpm-lock.yaml +++ b/common/config/rush/pnpm-lock.yaml @@ -490,10 +490,23 @@ packages: hasBin: true resolution: integrity: sha512-kd2kakdDoRgI54J5H11a76hyYZBMhtp4piwWAy4bYTwlQT0v/tp+G/UMMgjUL4vKf0kTNhitEUX/0LfQb1AHzQ== + /@microsoft/tsdoc-config/0.13.9: + dependencies: + '@microsoft/tsdoc': 0.12.24 + ajv: 6.12.6 + jju: 1.4.0 + resolve: 1.19.0 + dev: false + resolution: + integrity: sha512-VqqZn+rT9f6XujFPFR2aN9XKF/fuir/IzKVzoxI0vXIzxysp4ee6S2jCakmlGFHEasibifFTsJr7IYmRPxfzYw== /@microsoft/tsdoc/0.12.19: dev: false resolution: integrity: sha512-IpgPxHrNxZiMNUSXqR1l/gePKPkfAmIKoDRP9hp7OwjU29ZR8WCJsOJ8iBKgw0Qk+pFwR+8Y1cy8ImLY6e9m4A== + /@microsoft/tsdoc/0.12.24: + dev: false + resolution: + integrity: sha512-Mfmij13RUTmHEMi9vRUhMXD7rnGR2VvxeNYtaGtaJ4redwwjT4UXYJ+nzmVJF7hhd4pn/Fx5sncDKxMVFJSWPg== /@nodelib/fs.scandir/2.1.3: dependencies: '@nodelib/fs.stat': 2.0.3 @@ -2686,6 +2699,13 @@ packages: node: '>=6' resolution: integrity: sha512-VoM09vT7bfA7D+upt+FjeBO5eHIJQBUWki1aPvB+vbNiHS3+oGIJGIeyBtKQTME6UPXXy3vV07OL1tHd3ANuDw== + /eslint-plugin-tsdoc/0.2.10: + dependencies: + '@microsoft/tsdoc': 0.12.24 + '@microsoft/tsdoc-config': 0.13.9 + dev: false + resolution: + integrity: sha512-LDK6K0tQ7tIyVzyktwX7P9V/aZZOMSIGYRnDP3x6+obITkVyrCrkc5yUhBiUjTc/S9gEy5GpjwD02wgcMPBFbA== /eslint-scope/5.1.1: dependencies: esrecurse: 4.3.0 @@ -8432,7 +8452,7 @@ packages: dev: false name: '@rush-temp/communication-sms' resolution: - integrity: sha512-1P83NWkLnuPb7zQskpxAyoCQpElX6bjzVdyTv/YDvpxK4K8jseteRrKHIgQZcO/3gn/+KiTgO+gK1nxHE4ipRA== + integrity: sha512-lv8KbY4NtcT1BTIBNMoUC5iWh63xfZJX30ybkQ9MY9UuYQIVZNcyUk9hXIPuGg4Q9CVWcRWddEQpKIUvf2Ceng== tarball: 'file:projects/communication-sms.tgz' version: 0.0.0 'file:projects/core-amqp.tgz': @@ -9060,6 +9080,7 @@ packages: eslint-config-prettier: 7.0.0_eslint@7.15.0 eslint-plugin-no-only-tests: 2.4.0 eslint-plugin-promise: 4.2.1 + eslint-plugin-tsdoc: 0.2.10 glob: 7.1.6 mocha: 7.2.0 mocha-junit-reporter: 1.23.3_mocha@7.2.0 @@ -9071,7 +9092,7 @@ packages: dev: false name: '@rush-temp/eslint-plugin-azure-sdk' resolution: - integrity: sha512-yBwSqTdn2+fmwfY+QBCCXGqnC+OhHCKLxezTuOFKRpA0ObKvqymZIOJQgBINinAes2QOD9YfrU0EaQY3HWNneg== + integrity: sha512-2RtUxF0G9TkwYn+ZCfPc5pcFzpb+20NV+Nibj725uqFgdwuj20B8If1fkG6LaVqYKTEbJKJD837k6XU4EC6eyA== tarball: 'file:projects/eslint-plugin-azure-sdk.tgz' version: 0.0.0 'file:projects/event-hubs.tgz': diff --git a/common/tools/eslint-plugin-azure-sdk/package.json b/common/tools/eslint-plugin-azure-sdk/package.json index 17f8bea6f37a..8dab598bfec1 100644 --- a/common/tools/eslint-plugin-azure-sdk/package.json +++ b/common/tools/eslint-plugin-azure-sdk/package.json @@ -62,7 +62,8 @@ "@typescript-eslint/parser": "^4.9.0", "eslint": "^7.15.0", "eslint-plugin-no-only-tests": "^2.4.0", - "eslint-plugin-promise": "^4.2.1" + "eslint-plugin-promise": "^4.2.1", + "eslint-plugin-tsdoc": "^0.2.10" }, "dependencies": { "@typescript-eslint/typescript-estree": "^4.9.0", diff --git a/common/tools/eslint-plugin-azure-sdk/src/configs/azure-sdk-base.ts b/common/tools/eslint-plugin-azure-sdk/src/configs/azure-sdk-base.ts index b99159c566a5..8968fe93a1cf 100644 --- a/common/tools/eslint-plugin-azure-sdk/src/configs/azure-sdk-base.ts +++ b/common/tools/eslint-plugin-azure-sdk/src/configs/azure-sdk-base.ts @@ -11,7 +11,7 @@ export default { sourceType: "module", extraFileExtensions: [".json"] }, - plugins: ["@typescript-eslint", "no-only-tests", "promise"], + plugins: ["@typescript-eslint", "no-only-tests", "promise", "eslint-plugin-tsdoc"], extends: [ "plugin:@typescript-eslint/recommended", "eslint:recommended", @@ -111,6 +111,7 @@ export default { // https://github.com/Azure/azure-sdk-for-js/issues/7609 "@azure/azure-sdk/ts-pagination-list": "off", // https://github.com/Azure/azure-sdk-for-js/issues/7610 - "@azure/azure-sdk/ts-doc-internal": "off" + "@azure/azure-sdk/ts-doc-internal": "off", + "tsdoc/syntax": "error" } }; diff --git a/eng/tools/generate-doc/index.js b/eng/tools/generate-doc/index.js index 34e6e69630c8..d8c93c3c7dc8 100644 --- a/eng/tools/generate-doc/index.js +++ b/eng/tools/generate-doc/index.js @@ -147,6 +147,7 @@ const executeTypedoc = async (exclusionList, inclusionList, generateIndexWithTem "--excludeNotExported", '--exclude "node_modules/**/*"', "--ignoreCompilerErrors", + "--stripInternal", "--mode file", docOutputFolder, ]); diff --git a/sdk/anomalydetector/ai-anomaly-detector/src/AnomalyDetectorClient.ts b/sdk/anomalydetector/ai-anomaly-detector/src/AnomalyDetectorClient.ts index bfe27c751715..533e4f9801f2 100644 --- a/sdk/anomalydetector/ai-anomaly-detector/src/AnomalyDetectorClient.ts +++ b/sdk/anomalydetector/ai-anomaly-detector/src/AnomalyDetectorClient.ts @@ -44,7 +44,7 @@ export class AnomalyDetectorClient { /** * @internal - * @ignore + * @hidden * A reference to the auto-generated AnomalyDetector HTTP client. */ private client: GeneratedClient; @@ -61,9 +61,9 @@ export class AnomalyDetectorClient { * new AzureKeyCredential("") * ); * ``` - * @param string endpointUrl Url to an Azure Anomaly Detector service endpoint - * @param {TokenCredential | KeyCredential} credential Used to authenticate requests to the service. - * @param FormRecognizerClientOptions options Used to configure the Form Recognizer client. + * @param endpointUrl - Url to an Azure Anomaly Detector service endpoint + * @param credential - Used to authenticate requests to the service. + * @param options - Used to configure the Form Recognizer client. */ constructor( endpointUrl: string, @@ -107,9 +107,9 @@ export class AnomalyDetectorClient { * This operation generates a model using an entire series, each point is detected with the same model. * With this method, points before and after a certain point are used to determine whether it is an * anomaly. The entire detection can give user an overall status of the time series. - * @param body Time series points and period if needed. Advanced model parameters can also be set in + * @param body - Time series points and period if needed. Advanced model parameters can also be set in * the request. - * @param options The options parameters. + * @param options - The options parameters. */ public detectEntireSeries( body: DetectRequest, @@ -138,9 +138,9 @@ export class AnomalyDetectorClient { * This operation generates a model using points before the latest one. With this method, only * historical points are used to determine whether the target point is an anomaly. The latest point * detecting operation matches the scenario of real-time monitoring of business metrics. - * @param body Time series points and period if needed. Advanced model parameters can also be set in + * @param body - Time series points and period if needed. Advanced model parameters can also be set in * the request. - * @param options The options parameters. + * @param options - The options parameters. */ public detectLastPoint( body: DetectRequest, @@ -167,9 +167,9 @@ export class AnomalyDetectorClient { /** * Evaluate change point score of every series point - * @param body Time series points and granularity is needed. Advanced model parameters can also be set + * @param body - Time series points and granularity is needed. Advanced model parameters can also be set * in the request if needed. - * @param options The options parameters. + * @param options - The options parameters. */ detectChangePoint( body: DetectChangePointRequest, diff --git a/sdk/anomalydetector/ai-anomaly-detector/src/logger.ts b/sdk/anomalydetector/ai-anomaly-detector/src/logger.ts index 69bfa5d7bb23..da84a3e1573e 100644 --- a/sdk/anomalydetector/ai-anomaly-detector/src/logger.ts +++ b/sdk/anomalydetector/ai-anomaly-detector/src/logger.ts @@ -4,6 +4,6 @@ import { createClientLogger } from "@azure/logger"; /** - * The @azure/logger configuration for this package. + * The \@azure/logger configuration for this package. */ export const logger = createClientLogger("ai-anomaly-detector"); diff --git a/sdk/anomalydetector/ai-anomaly-detector/src/models.ts b/sdk/anomalydetector/ai-anomaly-detector/src/models.ts index 70b8289a7153..15c7af816c06 100644 --- a/sdk/anomalydetector/ai-anomaly-detector/src/models.ts +++ b/sdk/anomalydetector/ai-anomaly-detector/src/models.ts @@ -50,7 +50,7 @@ export interface DetectRequest { */ granularity: TimeGranularity; /** - * Custom Interval is used to set non-standard time interval, for example, if the series is 5 minutes, request can be set as {"granularity":"minutely", "customInterval":5}. + * Custom Interval is used to set non-standard time interval, for example, if the series is 5 minutes, request can be set as `{"granularity":"minutely", "customInterval":5}`. */ customInterval?: number; /** @@ -77,7 +77,7 @@ export interface DetectChangePointRequest { */ granularity: TimeGranularity; /** - * Custom Interval is used to set non-standard time interval, for example, if the series is 5 minutes, request can be set as {"granularity":"minutely", "customInterval":5}. + * Custom Interval is used to set non-standard time interval, for example, if the series is 5 minutes, request can be set as `{"granularity":"minutely", "customInterval":5}`. */ customInterval?: number; /** diff --git a/sdk/anomalydetector/ai-anomaly-detector/src/tracing.ts b/sdk/anomalydetector/ai-anomaly-detector/src/tracing.ts index dca468db5980..e3c65d41d26e 100644 --- a/sdk/anomalydetector/ai-anomaly-detector/src/tracing.ts +++ b/sdk/anomalydetector/ai-anomaly-detector/src/tracing.ts @@ -7,9 +7,10 @@ import { OperationOptions } from "@azure/core-http"; /** * Creates a span using the global tracer. - * @ignore - * @param name The name of the operation being performed. - * @param tracingOptions The options for the underlying http request. + * @internal + * @hidden + * @param name - The name of the operation being performed. + * @param tracingOptions - The options for the underlying http request. */ export function createSpan( operationName: string, diff --git a/sdk/anomalydetector/ai-anomaly-detector/tsdoc.json b/sdk/anomalydetector/ai-anomaly-detector/tsdoc.json new file mode 100644 index 000000000000..81c5a8a2aa2f --- /dev/null +++ b/sdk/anomalydetector/ai-anomaly-detector/tsdoc.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + "extends": ["../../../tsdoc.json"] +} diff --git a/sdk/core/abort-controller/src/AbortController.ts b/sdk/core/abort-controller/src/AbortController.ts index 235e22d09204..008b5be1c195 100644 --- a/sdk/core/abort-controller/src/AbortController.ts +++ b/sdk/core/abort-controller/src/AbortController.ts @@ -9,6 +9,7 @@ import { AbortSignal, abortSignal, AbortSignalLike } from "./AbortSignal"; * error matches `"AbortError"`. * * @example + * ```ts * const controller = new AbortController(); * controller.abort(); * try { @@ -18,6 +19,7 @@ import { AbortSignal, abortSignal, AbortSignalLike } from "./AbortSignal"; * // handle abort error here. * } * } + * ``` */ export class AbortError extends Error { constructor(message?: string) { @@ -31,44 +33,44 @@ export class AbortError extends Error { * that an asynchronous operation should be aborted. * * @example - * // Abort an operation when another event fires + * Abort an operation when another event fires + * ```ts * const controller = new AbortController(); * const signal = controller.signal; * doAsyncWork(signal); * button.addEventListener('click', () => controller.abort()); + * ``` * * @example - * // Share aborter cross multiple operations in 30s + * Share aborter cross multiple operations in 30s + * ```ts * // Upload the same data to 2 different data centers at the same time, * // abort another when any of them is finished * const controller = AbortController.withTimeout(30 * 1000); * doAsyncWork(controller.signal).then(controller.abort); * doAsyncWork(controller.signal).then(controller.abort); + *``` * * @example - * // Cascaded aborting + * Cascaded aborting + * ```ts * // All operations can't take more than 30 seconds * const aborter = Aborter.timeout(30 * 1000); * * // Following 2 operations can't take more than 25 seconds * await doAsyncWork(aborter.withTimeout(25 * 1000)); * await doAsyncWork(aborter.withTimeout(25 * 1000)); - * - * @export - * @class AbortController - * @implements {AbortSignalLike} + * ``` */ export class AbortController { private _signal: AbortSignal; /** - * @param {AbortSignalLike[]} [parentSignals] The AbortSignals that will signal aborted on the AbortSignal associated with this controller. - * @constructor + * @param parentSignals - The AbortSignals that will signal aborted on the AbortSignal associated with this controller. */ constructor(parentSignals?: AbortSignalLike[]); /** - * @param {...AbortSignalLike} parentSignals The AbortSignals that will signal aborted on the AbortSignal associated with this controller. - * @constructor + * @param parentSignals - The AbortSignals that will signal aborted on the AbortSignal associated with this controller. */ constructor(...parentSignals: AbortSignalLike[]); // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types @@ -102,8 +104,6 @@ export class AbortController { * when the abort method is called on this controller. * * @readonly - * @type {AbortSignal} - * @memberof AbortController */ public get signal(): AbortSignal { return this._signal; @@ -112,8 +112,6 @@ export class AbortController { /** * Signal that any operations passed this controller's associated abort signal * to cancel any remaining work and throw an `AbortError`. - * - * @memberof AbortController */ abort(): void { abortSignal(this._signal); @@ -121,10 +119,7 @@ export class AbortController { /** * Creates a new AbortSignal instance that will abort after the provided ms. - * - * @static - * @params {number} ms Elapsed time in milliseconds to trigger an abort. - * @returns {AbortSignal} + * @param ms - Elapsed time in milliseconds to trigger an abort. */ public static timeout(ms: number): AbortSignal { const signal = new AbortSignal(); diff --git a/sdk/core/abort-controller/src/AbortSignal.ts b/sdk/core/abort-controller/src/AbortSignal.ts index be35671bb859..3e3049ec4616 100644 --- a/sdk/core/abort-controller/src/AbortSignal.ts +++ b/sdk/core/abort-controller/src/AbortSignal.ts @@ -44,12 +44,10 @@ export interface AbortSignalLike { * cannot or will not ever be cancelled. * * @example - * // Abort without timeout + * Abort without timeout + * ```ts * await doAsyncWork(AbortSignal.none); - * - * @export - * @class AbortSignal - * @implements {AbortSignalLike} + * ``` */ export class AbortSignal implements AbortSignalLike { constructor() { @@ -61,8 +59,6 @@ export class AbortSignal implements AbortSignalLike { * Status of whether aborted or not. * * @readonly - * @type {boolean} - * @memberof AbortSignal */ public get aborted(): boolean { if (!abortedMap.has(this)) { @@ -76,9 +72,6 @@ export class AbortSignal implements AbortSignalLike { * Creates a new AbortSignal instance that will never be aborted. * * @readonly - * @static - * @type {AbortSignal} - * @memberof AbortSignal */ public static get none(): AbortSignal { return new AbortSignal(); @@ -86,17 +79,14 @@ export class AbortSignal implements AbortSignalLike { /** * onabort event listener. - * - * @memberof AbortSignal */ public onabort: ((ev?: Event) => any) | null = null; /** * Added new "abort" event listener, only support "abort" event. * - * @param {"abort"} _type Only support "abort" event - * @param {(this: AbortSignalLike, ev: any) => any} listener - * @memberof AbortSignal + * @param _type - Only support "abort" event + * @param listener - The listener to be added */ public addEventListener( // tslint:disable-next-line:variable-name @@ -114,9 +104,8 @@ export class AbortSignal implements AbortSignalLike { /** * Remove "abort" event listener, only support "abort" event. * - * @param {"abort"} _type Only support "abort" event - * @param {(this: AbortSignalLike, ev: any) => any} listener - * @memberof AbortSignal + * @param _type - Only support "abort" event + * @param listener - The listener to be removed */ public removeEventListener( // tslint:disable-next-line:variable-name diff --git a/sdk/core/core-auth/src/azureKeyCredential.ts b/sdk/core/core-auth/src/azureKeyCredential.ts index dc980abdd558..4e0caf2411be 100644 --- a/sdk/core/core-auth/src/azureKeyCredential.ts +++ b/sdk/core/core-auth/src/azureKeyCredential.ts @@ -29,7 +29,7 @@ export class AzureKeyCredential implements KeyCredential { * Create an instance of an AzureKeyCredential for use * with a service client. * - * @param key the initial value of the key to use in authentication + * @param key - The initial value of the key to use in authentication */ constructor(key: string) { if (!key) { @@ -45,7 +45,7 @@ export class AzureKeyCredential implements KeyCredential { * Updates will take effect upon the next request after * updating the key value. * - * @param newKey the new key value to be used + * @param newKey - The new key value to be used */ public update(newKey: string): void { this._key = newKey; diff --git a/sdk/core/core-auth/src/tokenCredential.ts b/sdk/core/core-auth/src/tokenCredential.ts index 17cea903c444..7f3f1c2360ad 100644 --- a/sdk/core/core-auth/src/tokenCredential.ts +++ b/sdk/core/core-auth/src/tokenCredential.ts @@ -14,8 +14,8 @@ export interface TokenCredential { * This method is called automatically by Azure SDK client libraries. You may call this method * directly, but you must also handle token caching and token refreshing. * - * @param scopes The list of scopes for which the token will have access. - * @param options The options used to configure any requests this + * @param scopes - The list of scopes for which the token will have access. + * @param options - The options used to configure any requests this * TokenCredential implementation might make. */ getToken(scopes: string | string[], options?: GetTokenOptions): Promise; @@ -67,7 +67,7 @@ export interface AccessToken { /** * Tests an object to determine whether it implements TokenCredential. * - * @param credential The assumed TokenCredential to be tested. + * @param credential - The assumed TokenCredential to be tested. */ export function isTokenCredential(credential: unknown): credential is TokenCredential { // Check for an object with a 'getToken' function and possibly with diff --git a/sdk/core/core-http/src/createSpan.ts b/sdk/core/core-http/src/createSpan.ts index 493a7de6bcb4..d7029a039e9f 100644 --- a/sdk/core/core-http/src/createSpan.ts +++ b/sdk/core/core-http/src/createSpan.ts @@ -23,9 +23,9 @@ export interface SpanConfig { /** * Creates a function called createSpan to create spans using the global tracer. - * @ignore - * @param spanConfig The name of the operation being performed. - * @param tracingOptions The options for the underlying http request. + * @hidden + * @param spanConfig - The name of the operation being performed. + * @param tracingOptions - The options for the underlying http request. */ export function createSpanFunction({ packagePrefix, namespace }: SpanConfig) { return function( diff --git a/sdk/core/core-http/src/credentials/accessTokenCache.ts b/sdk/core/core-http/src/credentials/accessTokenCache.ts index 2283251a49f8..8db75dad74ed 100644 --- a/sdk/core/core-http/src/credentials/accessTokenCache.ts +++ b/sdk/core/core-http/src/credentials/accessTokenCache.ts @@ -16,7 +16,7 @@ export interface AccessTokenCache { /** * Sets the cached token. * - * @param The {@link AccessToken} to be cached or null to + * @param accessToken - The {@link AccessToken} to be cached or null to * clear the cached token. */ setCachedToken(accessToken: AccessToken | undefined): void; diff --git a/sdk/core/core-http/src/credentials/accessTokenRefresher.ts b/sdk/core/core-http/src/credentials/accessTokenRefresher.ts index c0de93e89f5f..af902deb5927 100644 --- a/sdk/core/core-http/src/credentials/accessTokenRefresher.ts +++ b/sdk/core/core-http/src/credentials/accessTokenRefresher.ts @@ -20,7 +20,7 @@ export class AccessTokenRefresher { * Returns true if the required milliseconds(defaulted to 30000) have been passed signifying * that we are ready for a new refresh. * - * @returns {boolean} + * @returns */ public isReady(): boolean { // We're only ready for a new refresh if the required milliseconds have passed. @@ -34,7 +34,7 @@ export class AccessTokenRefresher { * then requests a new token, * then sets this.promise to undefined, * then returns the token. - * @param options getToken options + * @param options - */ private async getToken(options: GetTokenOptions): Promise { this.lastCalled = Date.now(); @@ -46,7 +46,7 @@ export class AccessTokenRefresher { /** * Requests a new token if we're not currently waiting for a new token. * Returns null if the required time between each call hasn't been reached. - * @param options getToken options + * @param options - */ public refresh(options: GetTokenOptions): Promise { if (!this.promise) { diff --git a/sdk/core/core-http/src/credentials/apiKeyCredentials.ts b/sdk/core/core-http/src/credentials/apiKeyCredentials.ts index fa8a5e4e88f0..74905e178587 100644 --- a/sdk/core/core-http/src/credentials/apiKeyCredentials.ts +++ b/sdk/core/core-http/src/credentials/apiKeyCredentials.ts @@ -6,7 +6,6 @@ import { WebResourceLike } from "../webResource"; import { ServiceClientCredentials } from "./serviceClientCredentials"; /** - * @interface ApiKeyCredentialOptions * Describes the options to be provided while creating an instance of ApiKeyCredentials */ export interface ApiKeyCredentialOptions { @@ -34,8 +33,7 @@ export class ApiKeyCredentials implements ServiceClientCredentials { private readonly inQuery?: { [x: string]: any }; /** - * @constructor - * @param {object} options Specifies the options to be provided for auth. Either header or query needs to be provided. + * @param options - Specifies the options to be provided for auth. Either header or query needs to be provided. */ constructor(options: ApiKeyCredentialOptions) { if (!options || (options && !options.inHeader && !options.inQuery)) { @@ -50,8 +48,8 @@ export class ApiKeyCredentials implements ServiceClientCredentials { /** * Signs a request with the values provided in the inHeader and inQuery parameter. * - * @param {WebResourceLike} webResource The WebResourceLike to be signed. - * @returns {Promise} The signed request object. + * @param webResource - The WebResourceLike to be signed. + * @returns The signed request object. */ signRequest(webResource: WebResourceLike): Promise { if (!webResource) { diff --git a/sdk/core/core-http/src/credentials/basicAuthenticationCredentials.ts b/sdk/core/core-http/src/credentials/basicAuthenticationCredentials.ts index 92541f1bdadf..406c11801a2f 100644 --- a/sdk/core/core-http/src/credentials/basicAuthenticationCredentials.ts +++ b/sdk/core/core-http/src/credentials/basicAuthenticationCredentials.ts @@ -17,10 +17,9 @@ export class BasicAuthenticationCredentials implements ServiceClientCredentials /** * Creates a new BasicAuthenticationCredentials object. * - * @constructor - * @param {string} userName User name. - * @param {string} password Password. - * @param {string} [authorizationScheme] The authorization scheme. + * @param userName - User name. + * @param password - Password. + * @param authorizationScheme - The authorization scheme. */ constructor( userName: string, @@ -41,8 +40,8 @@ export class BasicAuthenticationCredentials implements ServiceClientCredentials /** * Signs a request with the Authentication header. * - * @param {WebResourceLike} webResource The WebResourceLike to be signed. - * @returns {Promise} The signed request object. + * @param webResource - The WebResourceLike to be signed. + * @returns The signed request object. */ signRequest(webResource: WebResourceLike): Promise { const credentials = `${this.userName}:${this.password}`; diff --git a/sdk/core/core-http/src/credentials/serviceClientCredentials.ts b/sdk/core/core-http/src/credentials/serviceClientCredentials.ts index 86004e1773a1..4652d7a42ee4 100644 --- a/sdk/core/core-http/src/credentials/serviceClientCredentials.ts +++ b/sdk/core/core-http/src/credentials/serviceClientCredentials.ts @@ -7,8 +7,8 @@ export interface ServiceClientCredentials { /** * Signs a request with the Authentication header. * - * @param {WebResourceLike} webResource The WebResourceLike/request to be signed. - * @returns {Promise} The signed request object; + * @param webResource - The WebResourceLike/request to be signed. + * @returns The signed request object; */ signRequest(webResource: WebResourceLike): Promise; } diff --git a/sdk/core/core-http/src/credentials/topicCredentials.ts b/sdk/core/core-http/src/credentials/topicCredentials.ts index 872ce3f594f5..801dd2f01591 100644 --- a/sdk/core/core-http/src/credentials/topicCredentials.ts +++ b/sdk/core/core-http/src/credentials/topicCredentials.ts @@ -7,8 +7,7 @@ export class TopicCredentials extends ApiKeyCredentials { /** * Creates a new EventGrid TopicCredentials object. * - * @constructor - * @param {string} topicKey The EventGrid topic key + * @param topicKey - The EventGrid topic key */ constructor(topicKey: string) { if (!topicKey || (topicKey && typeof topicKey !== "string")) { diff --git a/sdk/core/core-http/src/httpHeaders.ts b/sdk/core/core-http/src/httpHeaders.ts index b84d9e5bbd39..3e6720e4a9ac 100644 --- a/sdk/core/core-http/src/httpHeaders.ts +++ b/sdk/core/core-http/src/httpHeaders.ts @@ -35,14 +35,14 @@ export interface HttpHeadersLike { /** * Set a header in this collection with the provided name and value. The name is * case-insensitive. - * @param headerName The name of the header to set. This value is case-insensitive. - * @param headerValue The value of the header to set. + * @param headerName - The name of the header to set. This value is case-insensitive. + * @param headerValue - The value of the header to set. */ set(headerName: string, headerValue: string | number): void; /** * Get the header value for the provided header name, or undefined if no header exists in this * collection with the provided name. - * @param headerName The name of the header. + * @param headerName - The name of the header. */ get(headerName: string): string | undefined; /** @@ -52,7 +52,7 @@ export interface HttpHeadersLike { /** * Remove the header with the provided headerName. Return whether or not the header existed and * was removed. - * @param headerName The name of the header to remove. + * @param headerName - The name of the header to remove. */ remove(headerName: string): boolean; /** @@ -133,8 +133,8 @@ export class HttpHeaders implements HttpHeadersLike { /** * Set a header in this collection with the provided name and value. The name is * case-insensitive. - * @param headerName The name of the header to set. This value is case-insensitive. - * @param headerValue The value of the header to set. + * @param headerName - The name of the header to set. This value is case-insensitive. + * @param headerValue - The value of the header to set. */ public set(headerName: string, headerValue: string | number): void { this._headersMap[getHeaderKey(headerName)] = { @@ -146,7 +146,7 @@ export class HttpHeaders implements HttpHeadersLike { /** * Get the header value for the provided header name, or undefined if no header exists in this * collection with the provided name. - * @param headerName The name of the header. + * @param headerName - The name of the header. */ public get(headerName: string): string | undefined { const header: HttpHeader = this._headersMap[getHeaderKey(headerName)]; @@ -163,7 +163,7 @@ export class HttpHeaders implements HttpHeadersLike { /** * Remove the header with the provided headerName. Return whether or not the header existed and * was removed. - * @param headerName The name of the header to remove. + * @param headerName - The name of the header to remove. */ public remove(headerName: string): boolean { const result: boolean = this.contains(headerName); diff --git a/sdk/core/core-http/src/httpPipelineLogger.ts b/sdk/core/core-http/src/httpPipelineLogger.ts index b82567ebd9d6..568ebf3079f9 100644 --- a/sdk/core/core-http/src/httpPipelineLogger.ts +++ b/sdk/core/core-http/src/httpPipelineLogger.ts @@ -15,8 +15,8 @@ export interface HttpPipelineLogger { /** * Log the provided message. - * @param logLevel The HttpLogDetailLevel associated with this message. - * @param message The message to log. + * @param logLevel - The HttpLogDetailLevel associated with this message. + * @param message - The message to log. */ log(logLevel: HttpPipelineLogLevel, message: string): void; } @@ -27,14 +27,14 @@ export interface HttpPipelineLogger { export class ConsoleHttpPipelineLogger implements HttpPipelineLogger { /** * Create a new ConsoleHttpPipelineLogger. - * @param minimumLogLevel The log level threshold for what logs will be logged. + * @param minimumLogLevel - The log level threshold for what logs will be logged. */ constructor(public minimumLogLevel: HttpPipelineLogLevel) {} /** * Log the provided message. - * @param logLevel The HttpLogDetailLevel associated with this message. - * @param message The message to log. + * @param logLevel - The HttpLogDetailLevel associated with this message. + * @param message - The message to log. */ log(logLevel: HttpPipelineLogLevel, message: string): void { const logMessage = `${HttpPipelineLogLevel[logLevel]}: ${message}`; diff --git a/sdk/core/core-http/src/operationOptions.ts b/sdk/core/core-http/src/operationOptions.ts index c55e408d4e01..e171be80ee95 100644 --- a/sdk/core/core-http/src/operationOptions.ts +++ b/sdk/core/core-http/src/operationOptions.ts @@ -25,8 +25,7 @@ export interface OperationOptions { export interface OperationRequestOptions { /** - * @property {object} [customHeaders] User defined custom request headers that - * will be applied before the request is sent. + * User defined custom request headers that will be applied before the request is sent. */ customHeaders?: { [key: string]: string }; @@ -54,7 +53,7 @@ export interface OperationRequestOptions { /** * Converts an OperationOptions to a RequestOptionsBase * - * @param opts OperationOptions object to convert to RequestOptionsBase + * @param opts - OperationOptions object to convert to RequestOptionsBase */ export function operationOptionsToRequestOptionsBase( opts: T diff --git a/sdk/core/core-http/src/operationParameter.ts b/sdk/core/core-http/src/operationParameter.ts index 1ba8aa823c82..655af9e9e1a6 100644 --- a/sdk/core/core-http/src/operationParameter.ts +++ b/sdk/core/core-http/src/operationParameter.ts @@ -51,7 +51,7 @@ export interface OperationQueryParameter extends OperationParameter { /** * Get the path to this parameter's value as a dotted string (a.b.c). - * @param parameter The parameter to get the path string for. + * @param parameter - The parameter to get the path string for. * @returns The path to this parameter's value as a dotted string. */ export function getPathStringFromParameter(parameter: OperationParameter): string { diff --git a/sdk/core/core-http/src/policies/bearerTokenAuthenticationPolicy.ts b/sdk/core/core-http/src/policies/bearerTokenAuthenticationPolicy.ts index a0e2f410f3fe..2441a332d907 100644 --- a/sdk/core/core-http/src/policies/bearerTokenAuthenticationPolicy.ts +++ b/sdk/core/core-http/src/policies/bearerTokenAuthenticationPolicy.ts @@ -25,8 +25,8 @@ const timeBetweenRefreshAttemptsInMs = 30000; /** * Creates a new BearerTokenAuthenticationPolicy factory. * - * @param credential The TokenCredential implementation that can supply the bearer token. - * @param scopes The scopes for which the bearer token applies. + * @param credential - The TokenCredential implementation that can supply the bearer token. + * @param scopes - The scopes for which the bearer token applies. */ export function bearerTokenAuthenticationPolicy( credential: TokenCredential, @@ -57,11 +57,11 @@ export class BearerTokenAuthenticationPolicy extends BaseRequestPolicy { /** * Creates a new BearerTokenAuthenticationPolicy object. * - * @param nextPolicy The next RequestPolicy in the request pipeline. - * @param options Options for this RequestPolicy. - * @param credential The TokenCredential implementation that can supply the bearer token. - * @param scopes The scopes for which the bearer token applies. - * @param tokenCache The cache for the most recent AccessToken returned from the TokenCredential. + * @param nextPolicy - The next RequestPolicy in the request pipeline. + * @param options - Options for this RequestPolicy. + * @param credential - The TokenCredential implementation that can supply the bearer token. + * @param scopes - The scopes for which the bearer token applies. + * @param tokenCache - The cache for the most recent AccessToken returned from the TokenCredential. */ constructor( nextPolicy: RequestPolicy, @@ -74,7 +74,7 @@ export class BearerTokenAuthenticationPolicy extends BaseRequestPolicy { /** * Applies the Bearer token to the request through the Authorization header. - * @param webResource + * @param webResource - */ public async sendRequest(webResource: WebResourceLike): Promise { if (!webResource.headers) webResource.headers = new HttpHeaders(); diff --git a/sdk/core/core-http/src/policies/disableResponseDecompressionPolicy.ts b/sdk/core/core-http/src/policies/disableResponseDecompressionPolicy.ts index 041cb95fbf3e..6f0b4472d52d 100644 --- a/sdk/core/core-http/src/policies/disableResponseDecompressionPolicy.ts +++ b/sdk/core/core-http/src/policies/disableResponseDecompressionPolicy.ts @@ -30,8 +30,8 @@ export class DisableResponseDecompressionPolicy extends BaseRequestPolicy { /** * Creates an instance of DisableResponseDecompressionPolicy. * - * @param {RequestPolicy} nextPolicy - * @param {RequestPolicyOptions} options + * @param nextPolicy - + * @param options - */ // The parent constructor is protected. /* eslint-disable-next-line @typescript-eslint/no-useless-constructor */ @@ -42,8 +42,8 @@ export class DisableResponseDecompressionPolicy extends BaseRequestPolicy { /** * Sends out request. * - * @param {WebResource} request - * @returns {Promise} + * @param request - + * @returns */ public async sendRequest(request: WebResource): Promise { request.decompressResponse = false; diff --git a/sdk/core/core-http/src/policies/exponentialRetryPolicy.ts b/sdk/core/core-http/src/policies/exponentialRetryPolicy.ts index 619c8cf064ee..89fbfb86c836 100644 --- a/sdk/core/core-http/src/policies/exponentialRetryPolicy.ts +++ b/sdk/core/core-http/src/policies/exponentialRetryPolicy.ts @@ -43,7 +43,6 @@ export function exponentialRetryPolicy( /** * Describes the Retry Mode type. Currently supporting only Exponential. - * @enum RetryMode */ export enum RetryMode { Exponential @@ -84,7 +83,6 @@ export const DefaultRetryOptions: RetryOptions = { }; /** - * @class * Instantiates a new "ExponentialRetryPolicyFilter" instance. */ export class ExponentialRetryPolicy extends BaseRequestPolicy { @@ -102,13 +100,12 @@ export class ExponentialRetryPolicy extends BaseRequestPolicy { maxRetryInterval: number; /** - * @constructor - * @param {RequestPolicy} nextPolicy The next RequestPolicy in the pipeline chain. - * @param {RequestPolicyOptions} options The options for this RequestPolicy. - * @param {number} [retryCount] The client retry count. - * @param {number} [retryInterval] The client retry interval, in milliseconds. - * @param {number} [minRetryInterval] The minimum retry interval, in milliseconds. - * @param {number} [maxRetryInterval] The maximum retry interval, in milliseconds. + * @param nextPolicy - The next RequestPolicy in the pipeline chain. + * @param options - The options for this RequestPolicy. + * @param retryCount - The client retry count. + * @param retryInterval - The client retry interval, in milliseconds. + * @param minRetryInterval - The minimum retry interval, in milliseconds. + * @param maxRetryInterval - The maximum retry interval, in milliseconds. */ constructor( nextPolicy: RequestPolicy, diff --git a/sdk/core/core-http/src/policies/keepAlivePolicy.ts b/sdk/core/core-http/src/policies/keepAlivePolicy.ts index f1aee2932e2a..3dab27385c95 100644 --- a/sdk/core/core-http/src/policies/keepAlivePolicy.ts +++ b/sdk/core/core-http/src/policies/keepAlivePolicy.ts @@ -41,9 +41,9 @@ export class KeepAlivePolicy extends BaseRequestPolicy { /** * Creates an instance of KeepAlivePolicy. * - * @param {RequestPolicy} nextPolicy - * @param {RequestPolicyOptions} options - * @param {KeepAliveOptions} [keepAliveOptions] + * @param nextPolicy - + * @param options - + * @param keepAliveOptions - */ constructor( nextPolicy: RequestPolicy, @@ -56,9 +56,8 @@ export class KeepAlivePolicy extends BaseRequestPolicy { /** * Sends out request. * - * @param {WebResourceLike} request - * @returns {Promise} - * @memberof KeepAlivePolicy + * @param request - + * @returns */ public async sendRequest(request: WebResourceLike): Promise { request.keepAlive = this.keepAliveOptions.enable; diff --git a/sdk/core/core-http/src/policies/ndJsonPolicy.ts b/sdk/core/core-http/src/policies/ndJsonPolicy.ts index 85719ceac038..c99c9c6b06ca 100644 --- a/sdk/core/core-http/src/policies/ndJsonPolicy.ts +++ b/sdk/core/core-http/src/policies/ndJsonPolicy.ts @@ -28,8 +28,8 @@ class NdJsonPolicy extends BaseRequestPolicy { /** * Creates an instance of KeepAlivePolicy. * - * @param nextPolicy - * @param options + * @param nextPolicy - + * @param options - */ constructor(nextPolicy: RequestPolicy, options: RequestPolicyOptions) { super(nextPolicy, options); @@ -38,7 +38,7 @@ class NdJsonPolicy extends BaseRequestPolicy { /** * Sends a request. * - * @param request + * @param request - */ public async sendRequest(request: WebResourceLike): Promise { // There currently isn't a good way to bypass the serializer diff --git a/sdk/core/core-http/src/policies/requestPolicy.ts b/sdk/core/core-http/src/policies/requestPolicy.ts index 0ab9a8fee95f..cee06504cb0d 100644 --- a/sdk/core/core-http/src/policies/requestPolicy.ts +++ b/sdk/core/core-http/src/policies/requestPolicy.ts @@ -27,7 +27,7 @@ export abstract class BaseRequestPolicy implements RequestPolicy { /** * Get whether or not a log with the provided log level should be logged. - * @param logLevel The log level of the log that will be logged. + * @param logLevel - The log level of the log that will be logged. * @returns Whether or not a log with the provided log level should be logged. */ public shouldLog(logLevel: HttpPipelineLogLevel): boolean { @@ -37,8 +37,8 @@ export abstract class BaseRequestPolicy implements RequestPolicy { /** * Attempt to log the provided message to the provided logger. If no logger was provided or if * the log level does not meat the logger's threshold, then nothing will be logged. - * @param logLevel The log level of this log. - * @param message The message of this log. + * @param logLevel - The log level of this log. + * @param message - The message of this log. */ public log(logLevel: HttpPipelineLogLevel, message: string): void { this._options.log(logLevel, message); @@ -51,7 +51,7 @@ export abstract class BaseRequestPolicy implements RequestPolicy { export interface RequestPolicyOptionsLike { /** * Get whether or not a log with the provided log level should be logged. - * @param logLevel The log level of the log that will be logged. + * @param logLevel - The log level of the log that will be logged. * @returns Whether or not a log with the provided log level should be logged. */ shouldLog(logLevel: HttpPipelineLogLevel): boolean; @@ -59,8 +59,8 @@ export interface RequestPolicyOptionsLike { /** * Attempt to log the provided message to the provided logger. If no logger was provided or if * the log level does not meet the logger's threshold, then nothing will be logged. - * @param logLevel The log level of this log. - * @param message The message of this log. + * @param logLevel - The log level of this log. + * @param message - The message of this log. */ log(logLevel: HttpPipelineLogLevel, message: string): void; } @@ -73,7 +73,7 @@ export class RequestPolicyOptions { /** * Get whether or not a log with the provided log level should be logged. - * @param logLevel The log level of the log that will be logged. + * @param logLevel - The log level of the log that will be logged. * @returns Whether or not a log with the provided log level should be logged. */ public shouldLog(logLevel: HttpPipelineLogLevel): boolean { @@ -87,8 +87,8 @@ export class RequestPolicyOptions { /** * Attempt to log the provided message to the provided logger. If no logger was provided or if * the log level does not meet the logger's threshold, then nothing will be logged. - * @param logLevel The log level of this log. - * @param message The message of this log. + * @param logLevel - The log level of this log. + * @param message - The message of this log. */ public log(logLevel: HttpPipelineLogLevel, message: string): void { if (this._logger && this.shouldLog(logLevel)) { diff --git a/sdk/core/core-http/src/policies/rpRegistrationPolicy.ts b/sdk/core/core-http/src/policies/rpRegistrationPolicy.ts index a3615ce71516..e23a50c0ee3b 100644 --- a/sdk/core/core-http/src/policies/rpRegistrationPolicy.ts +++ b/sdk/core/core-http/src/policies/rpRegistrationPolicy.ts @@ -68,9 +68,9 @@ function registerIfNeeded( /** * Reuses the headers of the original request and url (if specified). - * @param {WebResourceLike} originalRequest The original request - * @param {boolean} reuseUrlToo Should the url from the original request be reused as well. Default false. - * @returns {object} A new request object with desired headers. + * @param originalRequest - The original request + * @param reuseUrlToo - Should the url from the original request be reused as well. Default false. + * @returns A new request object with desired headers. */ function getRequestEssentials( originalRequest: WebResourceLike, @@ -94,8 +94,8 @@ function getRequestEssentials( /** * Validates the error code and message associated with 409 response status code. If it matches to that of * RP not registered then it returns the name of the RP else returns undefined. - * @param {string} body The response body received after making the original request. - * @returns {string} The name of the RP if condition is satisfied else undefined. + * @param body - The response body received after making the original request. + * @returns The name of the RP if condition is satisfied else undefined. */ function checkRPNotRegisteredError(body: string): string { let result, responseBody; @@ -124,8 +124,8 @@ function checkRPNotRegisteredError(body: string): string { /** * Extracts the first part of the URL, just after subscription: * https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/ - * @param {string} url The original request url - * @returns {string} The url prefix as explained above. + * @param url - The original request url + * @returns The url prefix as explained above. */ function extractSubscriptionUrl(url: string): string { let result; @@ -140,12 +140,12 @@ function extractSubscriptionUrl(url: string): string { /** * Registers the given provider. - * @param {RPRegistrationPolicy} policy The RPRegistrationPolicy this function is being called against. - * @param {string} urlPrefix https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/ - * @param {string} provider The provider name to be registered. - * @param {WebResourceLike} originalRequest The original request sent by the user that returned a 409 response + * @param policy - The RPRegistrationPolicy this function is being called against. + * @param urlPrefix - https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/ + * @param provider - The provider name to be registered. + * @param originalRequest - The original request sent by the user that returned a 409 response * with a message that the provider is not registered. - * @param {registrationCallback} callback The callback that handles the RP registration + * @param callback - The callback that handles the RP registration */ function registerRP( policy: RPRegistrationPolicy, @@ -170,11 +170,11 @@ function registerRP( /** * Polls the registration status of the provider that was registered. Polling happens at an interval of 30 seconds. * Polling will happen till the registrationState property of the response body is "Registered". - * @param {RPRegistrationPolicy} policy The RPRegistrationPolicy this function is being called against. - * @param {string} url The request url for polling - * @param {WebResourceLike} originalRequest The original request sent by the user that returned a 409 response + * @param policy - The RPRegistrationPolicy this function is being called against. + * @param url - The request url for polling + * @param originalRequest - The original request sent by the user that returned a 409 response * with a message that the provider is not registered. - * @returns {Promise} True if RP Registration is successful. + * @returns True if RP Registration is successful. */ function getRegistrationStatus( policy: RPRegistrationPolicy, diff --git a/sdk/core/core-http/src/policies/systemErrorRetryPolicy.ts b/sdk/core/core-http/src/policies/systemErrorRetryPolicy.ts index ad354846f0c1..7586b140c9d5 100644 --- a/sdk/core/core-http/src/policies/systemErrorRetryPolicy.ts +++ b/sdk/core/core-http/src/policies/systemErrorRetryPolicy.ts @@ -43,14 +43,10 @@ export function systemErrorRetryPolicy( } /** - * @class - * Instantiates a new "ExponentialRetryPolicyFilter" instance. - * - * @constructor - * @param {number} retryCount The client retry count. - * @param {number} retryInterval The client retry interval, in milliseconds. - * @param {number} minRetryInterval The minimum retry interval, in milliseconds. - * @param {number} maxRetryInterval The maximum retry interval, in milliseconds. + * @param retryCount - The client retry count. + * @param retryInterval - The client retry interval, in milliseconds. + * @param minRetryInterval - The minimum retry interval, in milliseconds. + * @param maxRetryInterval - The maximum retry interval, in milliseconds. */ export class SystemErrorRetryPolicy extends BaseRequestPolicy { retryCount: number; diff --git a/sdk/core/core-http/src/serializer.ts b/sdk/core/core-http/src/serializer.ts index f81384edc4cf..2332ee220a23 100644 --- a/sdk/core/core-http/src/serializer.ts +++ b/sdk/core/core-http/src/serializer.ts @@ -82,15 +82,11 @@ export class Serializer { /** * Serialize the given object based on its metadata defined in the mapper * - * @param {Mapper} mapper The mapper which defines the metadata of the serializable object - * - * @param {object|string|Array|number|boolean|Date|stream} object A valid Javascript object to be serialized - * - * @param {string} objectName Name of the serialized object - * - * @param {options} options additional options to deserialization - * - * @returns {object|string|Array|number|boolean|Date|stream} A valid serialized Javascript object + * @param mapper - The mapper which defines the metadata of the serializable object + * @param object - A valid Javascript object to be serialized + * @param objectName - Name of the serialized object + * @param options - additional options to deserialization + * @returns A valid serialized Javascript object */ serialize( mapper: Mapper, @@ -193,15 +189,11 @@ export class Serializer { /** * Deserialize the given object based on its metadata defined in the mapper * - * @param {object} mapper The mapper which defines the metadata of the serializable object - * - * @param {object|string|Array|number|boolean|Date|stream} responseBody A valid Javascript entity to be deserialized - * - * @param {string} objectName Name of the deserialized object - * - * @param options Controls behavior of XML parser and builder. - * - * @returns {object|string|Array|number|boolean|Date|stream} A valid deserialized Javascript object + * @param mapper - The mapper which defines the metadata of the serializable object + * @param responseBody - A valid Javascript entity to be deserialized + * @param objectName - Name of the deserialized object + * @param options - Controls behavior of XML parser and builder. + * @returns A valid deserialized Javascript object */ deserialize( mapper: Mapper, @@ -605,9 +597,9 @@ function serializeDictionaryType( /** * Resolves the additionalProperties property from a referenced mapper - * @param serializer the serializer containing the entire set of mappers - * @param mapper the composite mapper to resolve - * @param objectName name of the object being serialized + * @param serializer - The serializer containing the entire set of mappers + * @param mapper - The composite mapper to resolve + * @param objectName - Name of the object being serialized */ function resolveAdditionalProperties( serializer: Serializer, @@ -626,9 +618,9 @@ function resolveAdditionalProperties( /** * Finds the mapper referenced by className - * @param serializer the serializer containing the entire set of mappers - * @param mapper the composite mapper to resolve - * @param objectName name of the object being serialized + * @param serializer - The serializer containing the entire set of mappers + * @param mapper - The composite mapper to resolve + * @param objectName - Name of the object being serialized */ function resolveReferencedMapper( serializer: Serializer, @@ -651,8 +643,8 @@ function resolveReferencedMapper( /** * Resolves a composite mapper's modelProperties. - * @param serializer the serializer containing the entire set of mappers - * @param mapper the composite mapper to resolve + * @param serializer - The serializer containing the entire set of mappers + * @param mapper - The composite mapper to resolve */ function resolveModelProperties( serializer: Serializer, diff --git a/sdk/core/core-http/src/serviceClient.ts b/sdk/core/core-http/src/serviceClient.ts index 284682484d8e..4c003db73264 100644 --- a/sdk/core/core-http/src/serviceClient.ts +++ b/sdk/core/core-http/src/serviceClient.ts @@ -158,8 +158,7 @@ export interface ServiceClientOptions { } /** - * @class - * Initializes a new instance of the ServiceClient. + * ServiceClient sends service requests and receives responses. */ export class ServiceClient { /** @@ -185,9 +184,8 @@ export class ServiceClient { /** * The ServiceClient constructor - * @constructor - * @param credentials The credentials used for authentication with the service. - * @param options The service client options that govern the behavior of the client. + * @param credentials - The credentials used for authentication with the service. + * @param options - The service client options that govern the behavior of the client. */ constructor( credentials?: TokenCredential | ServiceClientCredentials, @@ -307,9 +305,9 @@ export class ServiceClient { /** * Send an HTTP request that is populated using the provided OperationSpec. - * @param {OperationArguments} operationArguments The arguments that the HTTP request's templated values will be populated from. - * @param {OperationSpec} operationSpec The OperationSpec to use to populate the httpRequest. - * @param {ServiceCallback} callback The callback to call when the response is received. + * @param operationArguments - The arguments that the HTTP request's templated values will be populated from. + * @param operationSpec - The OperationSpec to use to populate the httpRequest. + * @param callback - The callback to call when the response is received. */ async sendOperationRequest( operationArguments: OperationArguments, diff --git a/sdk/core/core-http/src/util/base64.browser.ts b/sdk/core/core-http/src/util/base64.browser.ts index 78aa705dfba6..98f804cffdbc 100644 --- a/sdk/core/core-http/src/util/base64.browser.ts +++ b/sdk/core/core-http/src/util/base64.browser.ts @@ -3,7 +3,7 @@ /** * Encodes a string in base64 format. - * @param value the string to encode + * @param value - The string to encode */ export function encodeString(value: string): string { return btoa(value); @@ -11,7 +11,7 @@ export function encodeString(value: string): string { /** * Encodes a byte array in base64 format. - * @param value the Uint8Aray to encode + * @param value - The Uint8Aray to encode */ export function encodeByteArray(value: Uint8Array): string { let str = ""; @@ -23,7 +23,7 @@ export function encodeByteArray(value: Uint8Array): string { /** * Decodes a base64 string into a byte array. - * @param value the base64 string to decode + * @param value - The base64 string to decode */ export function decodeString(value: string): Uint8Array { const byteString = atob(value); diff --git a/sdk/core/core-http/src/util/base64.ts b/sdk/core/core-http/src/util/base64.ts index c177d3096193..e1d5a49a4ba7 100644 --- a/sdk/core/core-http/src/util/base64.ts +++ b/sdk/core/core-http/src/util/base64.ts @@ -3,7 +3,7 @@ /** * Encodes a string in base64 format. - * @param value the string to encode + * @param value - The string to encode */ export function encodeString(value: string): string { return Buffer.from(value).toString("base64"); @@ -11,7 +11,7 @@ export function encodeString(value: string): string { /** * Encodes a byte array in base64 format. - * @param value the Uint8Aray to encode + * @param value - The Uint8Aray to encode */ export function encodeByteArray(value: Uint8Array): string { // Buffer.from accepts | -- the TypeScript definition is off here @@ -22,7 +22,7 @@ export function encodeByteArray(value: Uint8Array): string { /** * Decodes a base64 string into a byte array. - * @param value the base64 string to decode + * @param value - The base64 string to decode */ export function decodeString(value: string): Uint8Array { return Buffer.from(value, "base64"); diff --git a/sdk/core/core-http/src/util/constants.ts b/sdk/core/core-http/src/util/constants.ts index 294e1ec7312a..7332dadb0c78 100644 --- a/sdk/core/core-http/src/util/constants.ts +++ b/sdk/core/core-http/src/util/constants.ts @@ -4,65 +4,42 @@ export const Constants = { /** * The core-http version - * @const - * @type {string} */ coreHttpVersion: "1.2.1", /** * Specifies HTTP. - * - * @const - * @type {string} */ HTTP: "http:", /** * Specifies HTTPS. - * - * @const - * @type {string} */ HTTPS: "https:", /** * Specifies HTTP Proxy. - * - * @const - * @type {string} */ HTTP_PROXY: "HTTP_PROXY", /** * Specifies HTTPS Proxy. - * - * @const - * @type {string} */ HTTPS_PROXY: "HTTPS_PROXY", /** * Specifies NO Proxy. - * - * @const - * @type {string} */ NO_PROXY: "NO_PROXY", /** * Specifies ALL Proxy. - * - * @const - * @type {string} */ ALL_PROXY: "ALL_PROXY", HttpConstants: { /** * Http Verbs - * - * @const - * @enum {string} */ HttpVerbs: { PUT: "PUT", @@ -85,9 +62,6 @@ export const Constants = { HeaderConstants: { /** * The Authorization header. - * - * @const - * @type {string} */ AUTHORIZATION: "authorization", @@ -97,17 +71,11 @@ export const Constants = { * The Retry-After response-header field can be used with a 503 (Service * Unavailable) or 349 (Too Many Requests) responses to indicate how long * the service is expected to be unavailable to the requesting client. - * - * @const - * @type {string} */ RETRY_AFTER: "Retry-After", /** * The UserAgent header. - * - * @const - * @type {string} */ USER_AGENT: "User-Agent" } diff --git a/sdk/core/core-http/src/util/exponentialBackoffStrategy.ts b/sdk/core/core-http/src/util/exponentialBackoffStrategy.ts index db5918e87df4..a7fde6dfff8c 100644 --- a/sdk/core/core-http/src/util/exponentialBackoffStrategy.ts +++ b/sdk/core/core-http/src/util/exponentialBackoffStrategy.ts @@ -28,10 +28,10 @@ export interface RetryError extends Error { * @internal * Determines if the operation should be retried. * - * @param {number} retryLimit Specifies the max number of retries. - * @param {(response?: HttpOperationResponse, error?: RetryError) => boolean} predicate Initial chekck on whether to retry based on given responses or errors - * @param {RetryData} retryData The retry data. - * @return {boolean} True if the operation qualifies for a retry; false otherwise. + * @param retryLimit - Specifies the max number of retries. + * @param predicate - Initial chekck on whether to retry based on given responses or errors + * @param retryData - The retry data. + * @returns True if the operation qualifies for a retry; false otherwise. */ export function shouldRetry( retryLimit: number, @@ -51,9 +51,9 @@ export function shouldRetry( * @internal * Updates the retry data for the next attempt. * - * @param {RetryPolicyOptions} retryOptions specifies retry interval, and its lower bound and upper bound. - * @param {RetryData} [retryData] The retry data. - * @param {RetryError} [err] The operation"s error, if any. + * @param retryOptions - specifies retry interval, and its lower bound and upper bound. + * @param retryData - The retry data. + * @param err - The operation"s error, if any. */ export function updateRetryData( retryOptions: { retryInterval: number; minRetryInterval: number; maxRetryInterval: number }, diff --git a/sdk/core/core-http/src/util/utils.ts b/sdk/core/core-http/src/util/utils.ts index 1eea5adc640f..7c600721781f 100644 --- a/sdk/core/core-http/src/util/utils.ts +++ b/sdk/core/core-http/src/util/utils.ts @@ -22,8 +22,8 @@ export const isNode = /** * Checks if a parsed URL is HTTPS * - * @param {object} urlToCheck The url to check - * @return {boolean} True if the URL is HTTPS; false otherwise. + * @param urlToCheck - The url to check + * @returns True if the URL is HTTPS; false otherwise. */ export function urlIsHTTPS(urlToCheck: { protocol: string }): boolean { return urlToCheck.protocol.toLowerCase() === Constants.HTTPS; @@ -32,8 +32,8 @@ export function urlIsHTTPS(urlToCheck: { protocol: string }): boolean { /** * Encodes an URI. * - * @param {string} uri The URI to be encoded. - * @return {string} The encoded URI. + * @param uri - The URI to be encoded. + * @returns The encoded URI. */ export function encodeUri(uri: string): string { return encodeURIComponent(uri) @@ -48,9 +48,8 @@ export function encodeUri(uri: string): string { * Returns a stripped version of the Http Response which only contains body, * headers and the status. * - * @param {HttpOperationResponse} response The Http Response - * - * @return {object} The stripped version of Http Response. + * @param response - The Http Response + * @returns The stripped version of Http Response. */ export function stripResponse(response: HttpOperationResponse): any { const strippedResponse: any = {}; @@ -64,9 +63,8 @@ export function stripResponse(response: HttpOperationResponse): any { * Returns a stripped version of the Http Request that does not contain the * Authorization header. * - * @param {WebResourceLike} request The Http Request object - * - * @return {WebResourceLike} The stripped version of Http Request. + * @param request - The Http Request object + * @returns The stripped version of Http Request. */ export function stripRequest(request: WebResourceLike): WebResourceLike { const strippedRequest = request.clone(); @@ -79,9 +77,8 @@ export function stripRequest(request: WebResourceLike): WebResourceLike { /** * Validates the given uuid as a string * - * @param {string} uuid The uuid as a string that needs to be validated - * - * @return {boolean} True if the uuid is valid; false otherwise. + * @param uuid - The uuid as a string that needs to be validated + * @returns True if the uuid is valid; false otherwise. */ export function isValidUuid(uuid: string): boolean { return validUuidRegex.test(uuid); @@ -90,7 +87,7 @@ export function isValidUuid(uuid: string): boolean { /** * Generated UUID * - * @return {string} RFC4122 v4 UUID. + * @returns RFC4122 v4 UUID. */ export function generateUuid(): string { return uuidv4(); @@ -100,12 +97,10 @@ export function generateUuid(): string { * Executes an array of promises sequentially. Inspiration of this method is here: * https://pouchdb.com/2015/05/18/we-have-a-problem-with-promises.html. An awesome blog on promises! * - * @param {Array} promiseFactories An array of promise factories(A function that return a promise) - * - * @param {any} [kickstart] Input to the first promise that is used to kickstart the promise chain. + * @param promiseFactories - An array of promise factories(A function that return a promise) + * @param kickstart - Input to the first promise that is used to kickstart the promise chain. * If not provided then the promise chain starts with undefined. - * - * @return A chain of resolved or rejected promises + * @returns A chain of resolved or rejected promises */ export function executePromisesSequentially( promiseFactories: Array, @@ -120,9 +115,9 @@ export function executePromisesSequentially( /** * A wrapper for setTimeout that resolves a promise after t milliseconds. - * @param {number} t The number of milliseconds to be delayed. - * @param {T} value The value to be resolved with after a timeout of t milliseconds. - * @returns {Promise} Resolved promise + * @param t - The number of milliseconds to be delayed. + * @param value - The value to be resolved with after a timeout of t milliseconds. + * @returns Resolved promise */ export function delay(t: number, value?: T): Promise { return new Promise((resolve) => setTimeout(() => resolve(value), t)); @@ -134,10 +129,10 @@ export function delay(t: number, value?: T): Promise { export interface ServiceCallback { /** * A method that will be invoked as a callback to a service function. - * @param {Error | RestError | null} err The error occurred if any, while executing the request; otherwise null. - * @param {TResult} [result] The deserialized response body if an error did not occur. - * @param {WebResourceLike} [request] The raw/actual request sent to the server if an error did not occur. - * @param {HttpOperationResponse} [response] The raw/actual response from the server if an error did not occur. + * @param err - The error occurred if any, while executing the request; otherwise null. + * @param result - The deserialized response body if an error did not occur. + * @param request - The raw/actual request sent to the server if an error did not occur. + * @param response - The raw/actual response from the server if an error did not occur. */ ( err: Error | RestError | null, @@ -149,8 +144,8 @@ export interface ServiceCallback { /** * Converts a Promise to a callback. - * @param {Promise} promise The Promise to be converted to a callback - * @returns {Function} A function that takes the callback (cb: Function) => void + * @param promise - The Promise to be converted to a callback + * @returns A function that takes the callback `(cb: Function) => void` * @deprecated generated code should instead depend on responseToBody */ // eslint-disable-next-line @typescript-eslint/ban-types @@ -174,8 +169,8 @@ export function promiseToCallback(promise: Promise): (cb: Function) => void /** * Converts a Promise to a service callback. - * @param {Promise} promise - The Promise of HttpOperationResponse to be converted to a service callback - * @returns {Function} A function that takes the service callback (cb: ServiceCallback): void + * @param promise - The Promise of HttpOperationResponse to be converted to a service callback + * @returns A function that takes the service callback (cb: ServiceCallback): void */ export function promiseToServiceCallback( promise: Promise @@ -215,8 +210,8 @@ export function prepareXMLRootList( /** * Applies the properties on the prototype of sourceCtors to the prototype of targetCtor - * @param {object} targetCtor The target object on which the properties need to be applied. - * @param {Array} sourceCtors An array of source objects from which the properties need to be taken. + * @param targetCtor - The target object on which the properties need to be applied. + * @param sourceCtors - An array of source objects from which the properties need to be taken. */ export function applyMixins(targetCtorParam: unknown, sourceCtors: any[]): void { const castTargetCtorParam = targetCtorParam as { @@ -233,8 +228,8 @@ const validateISODuration = /^(-|\+)?P(?:([-+]?[0-9,.]*)Y)?(?:([-+]?[0-9,.]*)M)? /** * Indicates whether the given string is in ISO 8601 format. - * @param {string} value The value to be validated for ISO 8601 duration format. - * @return {boolean} `true` if valid, `false` otherwise. + * @param value - The value to be validated for ISO 8601 duration format. + * @returns `true` if valid, `false` otherwise. */ export function isDuration(value: string): boolean { return validateISODuration.test(value); @@ -242,10 +237,10 @@ export function isDuration(value: string): boolean { /** * Replace all of the instances of searchValue in value with the provided replaceValue. - * @param {string | undefined} value The value to search and replace in. - * @param {string} searchValue The value to search for in the value argument. - * @param {string} replaceValue The value to replace searchValue with in the value argument. - * @returns {string | undefined} The value where each instance of searchValue was replaced with replacedValue. + * @param value - The value to search and replace in. + * @param searchValue - The value to search for in the value argument. + * @param replaceValue - The value to replace searchValue with in the value argument. + * @returns The value where each instance of searchValue was replaced with replacedValue. */ export function replaceAll( value: string | undefined, @@ -258,8 +253,8 @@ export function replaceAll( /** * Determines whether the given entity is a basic/primitive type * (string, number, boolean, null, undefined). - * @param {any} value Any entity - * @return {boolean} - true is it is primitive type, false otherwise. + * @param value - Any entity + * @returns true is it is primitive type, false otherwise. */ export function isPrimitiveType(value: unknown): boolean { return (typeof value !== "object" && typeof value !== "function") || value === null; diff --git a/sdk/core/core-http/src/util/xml.ts b/sdk/core/core-http/src/util/xml.ts index 82fdd882edd2..bcc48cb46685 100644 --- a/sdk/core/core-http/src/util/xml.ts +++ b/sdk/core/core-http/src/util/xml.ts @@ -62,9 +62,8 @@ xml2jsBuilderSettings.renderOpts = { /** * Converts given JSON object to XML string - * @param obj JSON object to be converted into XML string - * @param opts Options that govern the parsing of given JSON object - * `rootName` indicates the name of the root element in the resulting XML + * @param obj - JSON object to be converted into XML string + * @param opts - Options that govern the parsing of given JSON object */ export function stringifyXML(obj: unknown, opts: SerializerOptions = {}): string { xml2jsBuilderSettings.rootName = opts.rootName; @@ -75,9 +74,8 @@ export function stringifyXML(obj: unknown, opts: SerializerOptions = {}): string /** * Converts given XML string into JSON - * @param str String containing the XML content to be parsed into JSON - * @param opts Options that govern the parsing of given xml string - * `includeRoot` indicates whether the root element is to be included or not in the output + * @param str - String containing the XML content to be parsed into JSON + * @param opts - Options that govern the parsing of given xml string */ export function parseXML(str: string, opts: SerializerOptions = {}): Promise { xml2jsParserSettings.explicitRoot = !!opts.includeRoot; diff --git a/sdk/core/core-http/src/webResource.ts b/sdk/core/core-http/src/webResource.ts index de666cd65047..7dca2f402327 100644 --- a/sdk/core/core-http/src/webResource.ts +++ b/sdk/core/core-http/src/webResource.ts @@ -173,8 +173,6 @@ export function isWebResourceLike(object: unknown): object is WebResourceLike { * * This class provides an abstraction over a REST call by being library / implementation agnostic and wrapping the necessary * properties to initiate a request. - * - * @constructor */ export class WebResource implements WebResourceLike { url: string; @@ -275,8 +273,8 @@ export class WebResource implements WebResourceLike { /** * Prepares the request. - * @param {RequestPrepareOptions} options Options to provide for preparing the request. - * @returns {WebResource} Returns the prepared WebResource (HTTP Request) object that needs to be given to the request pipeline. + * @param options - Options to provide for preparing the request. + * @returns Returns the prepared WebResource (HTTP Request) object that needs to be given to the request pipeline. */ prepare(options: RequestPrepareOptions): WebResource { if (!options) { @@ -492,7 +490,7 @@ export class WebResource implements WebResourceLike { /** * Clone this WebResource HTTP request object. - * @returns {WebResource} The clone of this WebResource HTTP request object. + * @returns The clone of this WebResource HTTP request object. */ clone(): WebResource { const result = new WebResource( @@ -550,15 +548,15 @@ export interface RequestPrepareOptions { * The "object" format should be used when you want to skip url encoding. While using the object format, * the object must have a property named value which provides the "query-parameter-value". * Example: - * - query-parameter-value in "object" format: { "query-parameter-name": { value: "query-parameter-value", skipUrlEncoding: true } } - * - query-parameter-value in "string" format: { "query-parameter-name": "query-parameter-value"}. + * - query-parameter-value in "object" format: `{ "query-parameter-name": { value: "query-parameter-value", skipUrlEncoding: true } }` + * - query-parameter-value in "string" format: `{ "query-parameter-name": "query-parameter-value"}`. * Note: "If options.url already has some query parameters, then the value provided in options.queryParameters will be appended to the url. */ queryParameters?: { [key: string]: any | ParameterValue }; /** * The path template of the request url. Either provide the "url" or provide the "pathTemplate" in * the options object. Both the options are mutually exclusive. - * Example: "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}" + * Example: `/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}` */ pathTemplate?: string; /** @@ -574,8 +572,8 @@ export interface RequestPrepareOptions { * The "object" format should be used when you want to skip url encoding. While using the object format, * the object must have a property named value which provides the "path-parameter-value". * Example: - * - path-parameter-value in "object" format: { "path-parameter-name": { value: "path-parameter-value", skipUrlEncoding: true } } - * - path-parameter-value in "string" format: { "path-parameter-name": "path-parameter-value" }. + * - path-parameter-value in "object" format: `{ "path-parameter-name": { value: "path-parameter-value", skipUrlEncoding: true } }` + * - path-parameter-value in "string" format: `{ "path-parameter-name": "path-parameter-value" }`. */ pathParameters?: { [key: string]: any | ParameterValue }; formData?: { [key: string]: any }; @@ -637,7 +635,6 @@ export interface ParameterValue { */ export interface RequestOptionsBase { /** - * @property {object} [customHeaders] User defined custom request headers that * will be applied before the request is sent. */ customHeaders?: { [key: string]: string }; diff --git a/sdk/core/core-http/test/data/TestClient/src/testClient.ts b/sdk/core/core-http/test/data/TestClient/src/testClient.ts index f84a863147c8..c41cfaa01c31 100644 --- a/sdk/core/core-http/test/data/TestClient/src/testClient.ts +++ b/sdk/core/core-http/test/data/TestClient/src/testClient.ts @@ -7,20 +7,8 @@ import * as msRest from "../../../../src/coreHttp"; import { Mappers } from "./models/mappers"; /** - * @class - * Initializes a new instance of the TestClient class. - * @constructor - * - * @param {string} [baseUri] - The base URI of the service. - * - * @param {object} [options] - The parameter options - * - * @param {Array} [options.filters] - Filters to be added to the request pipeline - * - * @param {object} [options.requestOptions] - Options for the underlying request object - * {@link https://github.com/request/request#requestoptions-callback Options doc} - * - * @param {bool} [options.noRetryPolicy] - If set to true, turn off default retry policy + * @param baseUri - The base URI of the service. + * @param options - The parameter options */ class TestClient extends msRest.ServiceClient { diff --git a/sdk/core/core-http/test/msAssert.ts b/sdk/core/core-http/test/msAssert.ts index 1dafb1a9b676..b56c6fb28d0c 100644 --- a/sdk/core/core-http/test/msAssert.ts +++ b/sdk/core/core-http/test/msAssert.ts @@ -7,8 +7,8 @@ import { assert } from "chai"; * Assert that the provided syncFunction throws an Error. If the expectedError is undefined, then * this function will just assert that an Error was thrown. If the expectedError is defined, then * this function will assert that the Error that was thrown is equal to the provided expectedError. - * @param syncFunction The synchronous function that is expected to thrown an Error. - * @param expectedError The Error that is expected to be thrown. + * @param syncFunction - The synchronous function that is expected to thrown an Error. + * @param expectedError - The Error that is expected to be thrown. */ export function throws( syncFunction: () => void, @@ -39,8 +39,8 @@ export function throws( * Assert that the provided asyncFunction throws an Error. If the expectedError is undefined, then * this function will just assert that an Error was thrown. If the expectedError is defined, then * this function will assert that the Error that was thrown is equal to the provided expectedError. - * @param asyncFunction The asynchronous function that is expected to thrown an Error. - * @param expectedError The Error that is expected to be thrown. + * @param asyncFunction - The asynchronous function that is expected to thrown an Error. + * @param expectedError - The Error that is expected to be thrown. */ export async function throwsAsync( asyncFunction: (() => Promise) | Promise, diff --git a/sdk/core/core-http/tsdoc.json b/sdk/core/core-http/tsdoc.json new file mode 100644 index 000000000000..81c5a8a2aa2f --- /dev/null +++ b/sdk/core/core-http/tsdoc.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + "extends": ["../../../tsdoc.json"] +} diff --git a/sdk/core/core-lro/src/pollOperation.ts b/sdk/core/core-lro/src/pollOperation.ts index dd4aedef9207..f52c200bae64 100644 --- a/sdk/core/core-lro/src/pollOperation.ts +++ b/sdk/core/core-lro/src/pollOperation.ts @@ -54,11 +54,11 @@ export interface PollOperation { /** * Defines how to request the remote service for updates on the status of the long running operation. * - * It optionally receives an object with an abortSignal property, from @azure/abort-controller's AbortSignalLike. + * It optionally receives an object with an abortSignal property, from \@azure/abort-controller's AbortSignalLike. * Also optionally receives a "fireProgress" function, which, if called, is responsible for triggering the * poller's onProgress callbacks. * - * @param options Optional properties passed to the operation's update method. + * @param options - Optional properties passed to the operation's update method. */ update(options?: { abortSignal?: AbortSignalLike; @@ -68,11 +68,11 @@ export interface PollOperation { /** * Attempts to cancel the underlying operation. * - * It only optionally receives an object with an abortSignal property, from @azure/abort-controller's AbortSignalLike. + * It only optionally receives an object with an abortSignal property, from \@azure/abort-controller's AbortSignalLike. * * It returns a promise that should be resolved with an updated version of the poller's operation. * - * @param options Optional properties passed to the operation's update method. + * @param options - Optional properties passed to the operation's update method. */ cancel(options?: { abortSignal?: AbortSignalLike }): Promise>; diff --git a/sdk/core/core-lro/src/poller.ts b/sdk/core/core-lro/src/poller.ts index 458c949bf44f..f05239622bee 100644 --- a/sdk/core/core-lro/src/poller.ts +++ b/sdk/core/core-lro/src/poller.ts @@ -179,7 +179,7 @@ export abstract class Poller, TResult protected operation: PollOperation; /** - * A poller needs to be initialized by passing in at least the basic properties of the PollOperation. + * A poller needs to be initialized by passing in at least the basic properties of the `PollOperation`. * * When writing an implementation of a Poller, this implementation needs to deal with the initialization * of any custom state beyond the basic definition of the poller. The basic poller assumes that the poller's @@ -241,7 +241,7 @@ export abstract class Poller, TResult * } * ``` * - * @param operation Must contain the basic properties of PollOperation. + * @param operation - Must contain the basic properties of `PollOperation`. */ constructor(operation: PollOperation) { this.operation = operation; @@ -266,7 +266,7 @@ export abstract class Poller, TResult * Defines how much to wait between each poll request. * This has to be implemented by your custom poller. * - * @azure/core-http has a simple implementation of a delay function that waits as many milliseconds as specified. + * \@azure/core-http has a simple implementation of a delay function that waits as many milliseconds as specified. * This can be used as follows: * * ```ts @@ -287,7 +287,7 @@ export abstract class Poller, TResult /** * @internal - * @ignore + * @hidden * Starts a loop that will break only if the poller is done * or if the poller is stopped. */ @@ -303,13 +303,13 @@ export abstract class Poller, TResult /** * @internal - * @ignore + * @hidden * pollOnce does one polling, by calling to the update method of the underlying * poll operation to make any relevant change effective. * - * It only optionally receives an object with an abortSignal property, from @azure/abort-controller's AbortSignalLike. + * It only optionally receives an object with an abortSignal property, from \@azure/abort-controller's AbortSignalLike. * - * @param options Optional properties passed to the operation's update method. + * @param options - Optional properties passed to the operation's update method. */ private async pollOnce(options: { abortSignal?: AbortSignalLike } = {}): Promise { const state: PollOperationState = this.operation.state; @@ -339,13 +339,13 @@ export abstract class Poller, TResult /** * @internal - * @ignore + * @hidden * fireProgress calls the functions passed in via onProgress the method of the poller. * * It loops over all of the callbacks received from onProgress, and executes them, sending them * the current operation state. * - * @param state The current operation state. + * @param state - The current operation state. */ private fireProgress(state: TState): void { for (const callback of this.pollProgressCallbacks) { @@ -355,7 +355,7 @@ export abstract class Poller, TResult /** * @internal - * @ignore + * @hidden * Invokes the underlying operation's cancel method, and rejects the * pollUntilDone promise. */ @@ -370,9 +370,9 @@ export abstract class Poller, TResult * Returns a promise that will resolve once a single polling request finishes. * It does this by calling the update method of the Poller's operation. * - * It only optionally receives an object with an abortSignal property, from @azure/abort-controller's AbortSignalLike. + * It only optionally receives an object with an abortSignal property, from \@azure/abort-controller's AbortSignalLike. * - * @param options Optional properties passed to the operation's update method. + * @param options - Optional properties passed to the operation's update method. */ public poll(options: { abortSignal?: AbortSignalLike } = {}): Promise { if (!this.pollOncePromise) { @@ -438,11 +438,11 @@ export abstract class Poller, TResult /** * Attempts to cancel the underlying operation. * - * It only optionally receives an object with an abortSignal property, from @azure/abort-controller's AbortSignalLike. + * It only optionally receives an object with an abortSignal property, from \@azure/abort-controller's AbortSignalLike. * * If it's called again before it finishes, it will throw an error. * - * @param options Optional properties passed to the operation's update method. + * @param options - Optional properties passed to the operation's update method. */ public cancelOperation(options: { abortSignal?: AbortSignalLike } = {}): Promise { if (!this.stopped) { diff --git a/sdk/core/core-lro/tsdoc.json b/sdk/core/core-lro/tsdoc.json new file mode 100644 index 000000000000..81c5a8a2aa2f --- /dev/null +++ b/sdk/core/core-lro/tsdoc.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + "extends": ["../../../tsdoc.json"] +} diff --git a/sdk/core/core-tracing/src/tracerProxy.ts b/sdk/core/core-tracing/src/tracerProxy.ts index c271d73b9c2b..53ee934de2f5 100644 --- a/sdk/core/core-tracing/src/tracerProxy.ts +++ b/sdk/core/core-tracing/src/tracerProxy.ts @@ -16,7 +16,7 @@ function getDefaultTracer(): Tracer { /** * Sets the global tracer, enabling tracing for the Azure SDK. - * @param tracer An OpenTelemetry Tracer instance. + * @param tracer - An OpenTelemetry Tracer instance. */ export function setTracer(tracer: Tracer): void { const cache = getCache(); diff --git a/sdk/core/core-tracing/src/tracers/noop/noOpSpan.ts b/sdk/core/core-tracing/src/tracers/noop/noOpSpan.ts index cf86ef5e6f98..40d67f76bcd9 100644 --- a/sdk/core/core-tracing/src/tracers/noop/noOpSpan.ts +++ b/sdk/core/core-tracing/src/tracers/noop/noOpSpan.ts @@ -20,7 +20,7 @@ export class NoOpSpan implements Span { /** * Marks the end of Span execution. - * @param _endTime The time to use as the Span's end time. Defaults to + * @param _endTime - The time to use as the Span's end time. Defaults to * the current time. */ end(_endTime?: number): void { @@ -29,8 +29,8 @@ export class NoOpSpan implements Span { /** * Sets an attribute on the Span - * @param _key the attribute key - * @param _value the attribute value + * @param _key - The attribute key + * @param _value - The attribute value */ setAttribute(_key: string, _value: unknown): this { return this; @@ -38,7 +38,7 @@ export class NoOpSpan implements Span { /** * Sets attributes on the Span - * @param _attributes the attributes to add + * @param _attributes - The attributes to add */ setAttributes(_attributes: Attributes): this { return this; @@ -46,8 +46,8 @@ export class NoOpSpan implements Span { /** * Adds an event to the Span - * @param _name The name of the event - * @param _attributes The associated attributes to add for this event + * @param _name - The name of the event + * @param _attributes - The associated attributes to add for this event */ addEvent(_name: string, _attributes?: Attributes): this { return this; @@ -55,7 +55,7 @@ export class NoOpSpan implements Span { /** * Sets a status on the span. Overrides the default of CanonicalCode.OK. - * @param _status The status to set. + * @param _status - The status to set. */ setStatus(_status: Status): this { return this; @@ -63,7 +63,7 @@ export class NoOpSpan implements Span { /** * Updates the name of the Span - * @param _name the new Span name + * @param _name - the new Span name */ updateName(_name: string): this { return this; diff --git a/sdk/core/core-tracing/src/tracers/noop/noOpTracer.ts b/sdk/core/core-tracing/src/tracers/noop/noOpTracer.ts index 5f5f4a0e6ebb..6e0ac5f72057 100644 --- a/sdk/core/core-tracing/src/tracers/noop/noOpTracer.ts +++ b/sdk/core/core-tracing/src/tracers/noop/noOpTracer.ts @@ -11,8 +11,8 @@ import { Tracer, Span, SpanOptions } from "@opentelemetry/api"; export class NoOpTracer implements Tracer { /** * Starts a new Span. - * @param _name The name of the span. - * @param _options The SpanOptions used during Span creation. + * @param _name - The name of the span. + * @param _options - The SpanOptions used during Span creation. */ startSpan(_name: string, _options?: SpanOptions): Span { return new NoOpSpan(); @@ -27,8 +27,8 @@ export class NoOpTracer implements Tracer { /** * Executes the given function within the context provided by a Span. - * @param _span The span that provides the context. - * @param fn The function to be executed. + * @param _span - The span that provides the context. + * @param fn - The function to be executed. */ withSpan ReturnType>(_span: Span, fn: T): ReturnType { return fn(); @@ -36,8 +36,8 @@ export class NoOpTracer implements Tracer { /** * Bind a Span as the target's scope - * @param target An object to bind the scope. - * @param _span A specific Span to use. Otherwise, use the current one. + * @param target - An object to bind the scope. + * @param _span - A specific Span to use. Otherwise, use the current one. */ bind(target: T, _span?: Span): T { return target; diff --git a/sdk/core/core-tracing/src/tracers/opencensus/openCensusSpanWrapper.ts b/sdk/core/core-tracing/src/tracers/opencensus/openCensusSpanWrapper.ts index 45f8636ae350..ab8689543224 100644 --- a/sdk/core/core-tracing/src/tracers/opencensus/openCensusSpanWrapper.ts +++ b/sdk/core/core-tracing/src/tracers/opencensus/openCensusSpanWrapper.ts @@ -31,14 +31,14 @@ export class OpenCensusSpanWrapper implements Span { /** * Wraps an existing OpenCensus Span - * @param span A Span or RootSpan from OpenCensus + * @param span - A Span or RootSpan from OpenCensus */ constructor(span: OpenCensusSpan); /** * Create a new OpenCensus Span and wrap it. - * @param tracer The OpenCensus tracer that has been wrapped in OpenCensusTracerWrapper - * @param name The name of the Span - * @param options Options for the Span + * @param tracer - The OpenCensus tracer that has been wrapped in OpenCensusTracerWrapper + * @param name - The name of the Span + * @param options - Options for the Span */ constructor(tracer: OpenCensusTracerWrapper, name: string, options?: SpanOptions); constructor( @@ -71,7 +71,7 @@ export class OpenCensusSpanWrapper implements Span { /** * Marks the end of Span execution. - * @param endTime The time to use as the Span's end time. Defaults to + * @param endTime - The time to use as the Span's end time. Defaults to * the current time. */ end(_endTime?: number): void { @@ -94,8 +94,8 @@ export class OpenCensusSpanWrapper implements Span { /** * Sets an attribute on the Span - * @param key the attribute key - * @param value the attribute value + * @param key - The attribute key + * @param value - The attribute value */ setAttribute(key: string, value: unknown): this { this._span.addAttribute(key, value as any); @@ -104,7 +104,7 @@ export class OpenCensusSpanWrapper implements Span { /** * Sets attributes on the Span - * @param attributes the attributes to add + * @param attributes - The attributes to add */ setAttributes(attributes: Attributes): this { this._span.attributes = attributes as OpenCensusAttributes; @@ -113,8 +113,8 @@ export class OpenCensusSpanWrapper implements Span { /** * Adds an event to the Span - * @param name The name of the event - * @param attributes The associated attributes to add for this event + * @param name - The name of the event + * @param attributes - The associated attributes to add for this event */ addEvent(_name: string, _attributes?: Attributes): this { throw new Error("Method not implemented."); @@ -122,7 +122,7 @@ export class OpenCensusSpanWrapper implements Span { /** * Sets a status on the span. Overrides the default of CanonicalCode.OK. - * @param status The status to set. + * @param status - The status to set. */ setStatus(status: Status): this { this._span.setStatus(status.code, status.message); @@ -131,7 +131,7 @@ export class OpenCensusSpanWrapper implements Span { /** * Updates the name of the Span - * @param name the new Span name + * @param name - The new Span name */ updateName(name: string): this { this._span.name = name; diff --git a/sdk/core/core-tracing/src/tracers/opencensus/openCensusTraceStateWrapper.ts b/sdk/core/core-tracing/src/tracers/opencensus/openCensusTraceStateWrapper.ts index e5851fda3fde..723899560e5d 100644 --- a/sdk/core/core-tracing/src/tracers/opencensus/openCensusTraceStateWrapper.ts +++ b/sdk/core/core-tracing/src/tracers/opencensus/openCensusTraceStateWrapper.ts @@ -4,7 +4,7 @@ import { TraceState } from "@opentelemetry/api"; /** - * @ignore + * @hidden * @internal */ export class OpenCensusTraceStateWrapper implements TraceState { diff --git a/sdk/core/core-tracing/src/tracers/opencensus/openCensusTracerWrapper.ts b/sdk/core/core-tracing/src/tracers/opencensus/openCensusTracerWrapper.ts index a397a6384b7f..3309eeee2d45 100644 --- a/sdk/core/core-tracing/src/tracers/opencensus/openCensusTracerWrapper.ts +++ b/sdk/core/core-tracing/src/tracers/opencensus/openCensusTracerWrapper.ts @@ -20,7 +20,7 @@ export class OpenCensusTracerWrapper implements Tracer { /** * Create a new wrapper around a given OpenCensus Tracer. - * @param tracer The OpenCensus Tracer to wrap. + * @param tracer - The OpenCensus Tracer to wrap. */ public constructor(tracer: OpenCensusTracer) { this._tracer = tracer; @@ -28,8 +28,8 @@ export class OpenCensusTracerWrapper implements Tracer { /** * Starts a new Span. - * @param name The name of the span. - * @param options The SpanOptions used during Span creation. + * @param name - The name of the span. + * @param options - The SpanOptions used during Span creation. */ startSpan(name: string, options?: SpanOptions): Span { return new OpenCensusSpanWrapper(this, name, options); @@ -44,8 +44,8 @@ export class OpenCensusTracerWrapper implements Tracer { /** * Executes the given function within the context provided by a Span. - * @param _span The span that provides the context. - * @param _fn The function to be executed. + * @param _span - The span that provides the context. + * @param _fn - The function to be executed. */ withSpan unknown>(_span: Span, _fn: T): ReturnType { throw new Error("Method not implemented."); @@ -53,8 +53,8 @@ export class OpenCensusTracerWrapper implements Tracer { /** * Bind a Span as the target's scope - * @param target An object to bind the scope. - * @param _span A specific Span to use. Otherwise, use the current one. + * @param target - An object to bind the scope. + * @param _span - A specific Span to use. Otherwise, use the current one. */ bind(_target: T, _span?: Span): T { throw new Error("Method not implemented."); diff --git a/sdk/core/core-tracing/src/tracers/test/testSpan.ts b/sdk/core/core-tracing/src/tracers/test/testSpan.ts index 4189a4d66e89..8c40dd29a259 100644 --- a/sdk/core/core-tracing/src/tracers/test/testSpan.ts +++ b/sdk/core/core-tracing/src/tracers/test/testSpan.ts @@ -56,12 +56,12 @@ export class TestSpan extends NoOpSpan { /** * Starts a new Span. - * @param parentTracer The tracer that created this Span - * @param name The name of the span. - * @param context The SpanContext this span belongs to - * @param kind The SpanKind of this Span - * @param parentSpanId The identifier of the parent Span - * @param startTime The startTime of the event (defaults to now) + * @param parentTracer- The tracer that created this Span + * @param name - The name of the span. + * @param context - The SpanContext this span belongs to + * @param kind - The SpanKind of this Span + * @param parentSpanId - The identifier of the parent Span + * @param startTime - The startTime of the event (defaults to now) */ constructor( parentTracer: Tracer, @@ -101,7 +101,7 @@ export class TestSpan extends NoOpSpan { /** * Marks the end of Span execution. - * @param _endTime The time to use as the Span's end time. Defaults to + * @param _endTime - The time to use as the Span's end time. Defaults to * the current time. */ end(_endTime?: number): void { @@ -110,7 +110,7 @@ export class TestSpan extends NoOpSpan { /** * Sets a status on the span. Overrides the default of CanonicalCode.OK. - * @param status The status to set. + * @param status - The status to set. */ setStatus(status: Status): this { this.status = status; @@ -126,8 +126,8 @@ export class TestSpan extends NoOpSpan { /** * Sets an attribute on the Span - * @param key the attribute key - * @param value the attribute value + * @param key - The attribute key + * @param value - The attribute value */ setAttribute(key: string, value: unknown): this { this.attributes[key] = value; @@ -136,7 +136,7 @@ export class TestSpan extends NoOpSpan { /** * Sets attributes on the Span - * @param attributes the attributes to add + * @param attributes - The attributes to add */ setAttributes(attributes: Attributes): this { for (const key of Object.keys(attributes)) { diff --git a/sdk/core/core-tracing/src/tracers/test/testTracer.ts b/sdk/core/core-tracing/src/tracers/test/testTracer.ts index 7d902a562bde..f1cc142b7e35 100644 --- a/sdk/core/core-tracing/src/tracers/test/testTracer.ts +++ b/sdk/core/core-tracing/src/tracers/test/testTracer.ts @@ -76,7 +76,7 @@ export class TestTracer extends NoOpTracer { /** * Return all Spans for a particular trace, grouped by their * parent Span in a tree-like structure - * @param traceId The traceId to return the graph for + * @param traceId - The traceId to return the graph for */ getSpanGraph(traceId: string): SpanGraph { const traceSpans = this.knownSpans.filter((span) => { @@ -113,8 +113,8 @@ export class TestTracer extends NoOpTracer { /** * Starts a new Span. - * @param name The name of the span. - * @param options The SpanOptions used during Span creation. + * @param name - The name of the span. + * @param options - The SpanOptions used during Span creation. */ startSpan(name: string, options: SpanOptions = {}): TestSpan { const parentContext = this._getParentContext(options); diff --git a/sdk/core/core-tracing/src/utils/traceParentHeader.ts b/sdk/core/core-tracing/src/utils/traceParentHeader.ts index c24ffdbf2d7a..657c59703c8a 100644 --- a/sdk/core/core-tracing/src/utils/traceParentHeader.ts +++ b/sdk/core/core-tracing/src/utils/traceParentHeader.ts @@ -7,7 +7,7 @@ const VERSION = "00"; /** * Generates a `SpanContext` given a `traceparent` header value. - * @param traceParent Serialized span context data as a `traceparent` header value. + * @param traceParent - Serialized span context data as a `traceparent` header value. * @returns The `SpanContext` generated from the `traceparent` value. */ export function extractSpanContextFromTraceParentHeader( @@ -38,7 +38,7 @@ export function extractSpanContextFromTraceParentHeader( /** * Generates a `traceparent` value given a span context. - * @param spanContext Contains context for a specific span. + * @param spanContext - Contains context for a specific span. * @returns The `spanContext` represented as a `traceparent` value. */ export function getTraceParentHeader(spanContext: SpanContext): string | undefined { diff --git a/sdk/core/core-tracing/tsdoc.json b/sdk/core/core-tracing/tsdoc.json new file mode 100644 index 000000000000..81c5a8a2aa2f --- /dev/null +++ b/sdk/core/core-tracing/tsdoc.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + "extends": ["../../../tsdoc.json"] +} diff --git a/sdk/core/logger/src/index.ts b/sdk/core/logger/src/index.ts index 1926230bb42c..f624985dcfc8 100644 --- a/sdk/core/logger/src/index.ts +++ b/sdk/core/logger/src/index.ts @@ -53,7 +53,7 @@ if (logLevelFromEnv) { /** * Immediately enables logging at the specified log level. - * @param level The log level to enable for logging. + * @param level - The log level to enable for logging. * Options from most verbose to least verbose are: * - verbose * - info @@ -122,8 +122,8 @@ export interface AzureLogger { /** * Creates a logger for use by the Azure SDKs that inherits from `AzureLogger`. - * @param namespace The name of the SDK package. - * @ignore + * @param namespace - The name of the SDK package. + * @hidden */ export function createClientLogger(namespace: string): AzureLogger { const clientRootLogger: AzureClientLogger = AzureLogger.extend(namespace); diff --git a/sdk/core/logger/tsdoc.json b/sdk/core/logger/tsdoc.json new file mode 100644 index 000000000000..81c5a8a2aa2f --- /dev/null +++ b/sdk/core/logger/tsdoc.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + "extends": ["../../../tsdoc.json"] +} diff --git a/sdk/eventgrid/eventgrid/src/consumer.ts b/sdk/eventgrid/eventgrid/src/consumer.ts index dcb69aafd1fa..1b61aa134403 100644 --- a/sdk/eventgrid/eventgrid/src/consumer.ts +++ b/sdk/eventgrid/eventgrid/src/consumer.ts @@ -54,7 +54,7 @@ export class EventGridConsumer { /** * Deserializes events encoded in the Event Grid schema. * - * @param encodedEvents the JSON encoded representation of either a single event or an array of + * @param encodedEvents - the JSON encoded representation of either a single event or an array of * events, encoded in the Event Grid Schema. */ public async deserializeEventGridEvents( @@ -64,7 +64,7 @@ export class EventGridConsumer { /** * Deserializes events encoded in the Event Grid schema. * - * @param encodedEvents an object representing a single event, encoded in the Event Grid schema. + * @param encodedEvents - an object representing a single event, encoded in the Event Grid schema. */ public async deserializeEventGridEvents( encodedEvents: object @@ -98,7 +98,7 @@ export class EventGridConsumer { /** * Deserializes events encoded in the Cloud Events 1.0 schema. * - * @param encodedEvents the JSON encoded representation of either a single event or an array of + * @param encodedEvents - the JSON encoded representation of either a single event or an array of * events, encoded in the Cloud Events 1.0 Schema. */ public async deserializeCloudEvents(encodedEvents: string): Promise[]>; @@ -106,7 +106,7 @@ export class EventGridConsumer { /** * Deserializes events encoded in the Cloud Events 1.0 schema. * - * @param encodedEvents an object representing a single event, encoded in the Cloud Events 1.0 schema. + * @param encodedEvents - an object representing a single event, encoded in the Cloud Events 1.0 schema. */ public async deserializeCloudEvents(encodedEvents: object): Promise[]>; public async deserializeCloudEvents( diff --git a/sdk/eventgrid/eventgrid/src/cryptoHelpers.browser.ts b/sdk/eventgrid/eventgrid/src/cryptoHelpers.browser.ts index e9c2986d66a0..9f357b242b07 100644 --- a/sdk/eventgrid/eventgrid/src/cryptoHelpers.browser.ts +++ b/sdk/eventgrid/eventgrid/src/cryptoHelpers.browser.ts @@ -5,7 +5,7 @@ /** * @internal - * @ignore + * @hidden */ export async function sha256Hmac(secret: string, stringToSign: string): Promise { const key = await self.crypto.subtle.importKey( diff --git a/sdk/eventgrid/eventgrid/src/cryptoHelpers.ts b/sdk/eventgrid/eventgrid/src/cryptoHelpers.ts index 85f2feb312ee..ca1b4df6b3c2 100644 --- a/sdk/eventgrid/eventgrid/src/cryptoHelpers.ts +++ b/sdk/eventgrid/eventgrid/src/cryptoHelpers.ts @@ -5,7 +5,7 @@ import { createHmac } from "crypto"; /** * @internal - * @ignore + * @hidden */ export async function sha256Hmac(secret: string, stringToSign: string): Promise { const decodedSecret = Buffer.from(secret, "base64"); diff --git a/sdk/eventgrid/eventgrid/src/eventGridClient.ts b/sdk/eventgrid/eventgrid/src/eventGridClient.ts index 4ca93dbec698..b688b8600175 100644 --- a/sdk/eventgrid/eventgrid/src/eventGridClient.ts +++ b/sdk/eventgrid/eventgrid/src/eventGridClient.ts @@ -88,9 +88,9 @@ export class EventGridPublisherClient { * ); * ``` * - * @param endpointUrl The URL to the EventGrid endpoint, e.g. https://eg-topic.westus2-1.eventgrid.azure.net/api/events - * @param credential Used to authenticate requests to the service. - * @param options Used to configure the Event Grid Client + * @param endpointUrl - The URL to the EventGrid endpoint, e.g. https://eg-topic.westus2-1.eventgrid.azure.net/api/events + * @param credential - Used to authenticate requests to the service. + * @param options - Used to configure the Event Grid Client */ constructor( endpointUrl: string, @@ -124,9 +124,9 @@ export class EventGridPublisherClient { } /** - * Publishes events in the Event Grid scheama. The topic must be configured to expect events in the Event Grid schema. + * Publishes events in the Event Grid schema. The topic must be configured to expect events in the Event Grid schema. * - * @param message One or more events to publish + * @param message - One or more events to publish */ async sendEvents( events: SendEventGridEventInput[], @@ -155,7 +155,7 @@ export class EventGridPublisherClient { /** * Publishes events in the Cloud Events 1.0 schema. The topic must be configured to expect events in the Cloud Events 1.0 schema. * - * @param message One or more events to publish + * @param message - One or more events to publish */ async sendCloudEvents( events: SendCloudEventInput[], @@ -184,7 +184,7 @@ export class EventGridPublisherClient { /** * Publishes events written using a custom schema. The topic must be configured to expect events in a custom schema. * - * @param message One or more events to publish + * @param message - One or more events to publish */ async sendCustomSchemaEvents( events: Record[], diff --git a/sdk/eventgrid/eventgrid/src/generateSharedAccessSignature.ts b/sdk/eventgrid/eventgrid/src/generateSharedAccessSignature.ts index ee9b2d381ed4..f9ab53bd21fd 100644 --- a/sdk/eventgrid/eventgrid/src/generateSharedAccessSignature.ts +++ b/sdk/eventgrid/eventgrid/src/generateSharedAccessSignature.ts @@ -18,10 +18,10 @@ export interface GenerateSharedAccessSignatureOptions { * Generate a shared access signature, which allows a client to send events to an Event Grid Topic or Domain for a limited period of time. This * function may only be called when the EventGridPublisherClient was constructed with a KeyCredential instance. * - * @param endpointUrl The endpoint for the topic or domain you wish to generate a shared access signature for. - * @param credential The credential to use when generating the shared access signatrue. - * @param expiresOn The time at which the shared access signature is no longer valid. - * @param options Options to control how the signature is generated. + * @param endpointUrl - The endpoint for the topic or domain you wish to generate a shared access signature for. + * @param credential - The credential to use when generating the shared access signatrue. + * @param expiresOn - The time at which the shared access signature is no longer valid. + * @param options - Options to control how the signature is generated. */ export async function generateSharedAccessSignature( endpointUrl: string, diff --git a/sdk/eventgrid/eventgrid/src/logger.ts b/sdk/eventgrid/eventgrid/src/logger.ts index 81ab74e89343..f2e4570c0105 100644 --- a/sdk/eventgrid/eventgrid/src/logger.ts +++ b/sdk/eventgrid/eventgrid/src/logger.ts @@ -4,6 +4,6 @@ import { createClientLogger } from "@azure/logger"; /** - * The @azure/logger configuration for this package. + * The \@azure/logger configuration for this package. */ export const logger = createClientLogger("eventgrid"); diff --git a/sdk/eventgrid/eventgrid/src/predicates.ts b/sdk/eventgrid/eventgrid/src/predicates.ts index 104418ab7178..b3fbaa08e082 100644 --- a/sdk/eventgrid/eventgrid/src/predicates.ts +++ b/sdk/eventgrid/eventgrid/src/predicates.ts @@ -209,7 +209,7 @@ export type KnownSystemEventTypes = /** * A mapping of event type names to event data type interfaces. * - * @ignore + * @hidden */ export interface SystemEventNameToEventData { /** An interface for the event data of a "Microsoft.Communication.ChatMessageReceived" event. */ @@ -411,7 +411,7 @@ export interface SystemEventNameToEventData { /** * isCloudEventLike returns "true" when the event is a CloudEvent * - * @param o Either an EventGrid our CloudEvent event. + * @param o - Either an EventGrid our CloudEvent event. */ function isCloudEventLike( o: EventGridEvent | CloudEvent @@ -424,8 +424,8 @@ function isCloudEventLike( * TypeScript, this function acts as a custom type guard and allows the TypeScript compiler to * identify the underlying data * - * @param eventType The type of system event to check for, e.g., "Microsoft.AppConfiguration.KeyValueDeleted" - * @param event The event to test. + * @param eventType - The type of system event to check for, e.g., "Microsoft.AppConfiguration.KeyValueDeleted" + * @param event - The event to test. */ export function isSystemEvent( eventType: T, @@ -437,8 +437,8 @@ export function isSystemEvent( * TypeScript, this function acts as a custom type guard and allows the TypeScript compiler to * identify the underlying data * - * @param eventType The type of system event to check for, e.g., "Microsoft.AppConfiguration.KeyValueDeleted" - * @param event The event to test. + * @param eventType - The type of system event to check for, e.g., "Microsoft.AppConfiguration.KeyValueDeleted" + * @param event - The event to test. */ export function isSystemEvent( eventType: T, diff --git a/sdk/eventgrid/eventgrid/src/sharedAccessSignitureCredential.ts b/sdk/eventgrid/eventgrid/src/sharedAccessSignitureCredential.ts index 73306480da20..34cd09e8c741 100644 --- a/sdk/eventgrid/eventgrid/src/sharedAccessSignitureCredential.ts +++ b/sdk/eventgrid/eventgrid/src/sharedAccessSignitureCredential.ts @@ -31,7 +31,7 @@ export class EventGridSharedAccessSignatureCredential implements SignatureCreden * Create an instance of an EventGridSharedAccessSignatureCredential for use * with a service client. * - * @param {string} signature the signature to use in authentication + * @param signature - The signature to use in authentication */ constructor(signature: string) { if (!signature) { @@ -47,7 +47,7 @@ export class EventGridSharedAccessSignatureCredential implements SignatureCreden * Updates will take effect upon the next request after * updating the signature value. * - * @param {string} newSignature the new signature value to be used + * @param newSignature - The new signature value to be used */ public update(newSignature: string): void { this._signature = newSignature; diff --git a/sdk/eventgrid/eventgrid/src/tracing.ts b/sdk/eventgrid/eventgrid/src/tracing.ts index 8d747dca28e0..6d028ef7de88 100644 --- a/sdk/eventgrid/eventgrid/src/tracing.ts +++ b/sdk/eventgrid/eventgrid/src/tracing.ts @@ -9,9 +9,10 @@ type OperationTracingOptions = OperationOptions["tracingOptions"]; /** * Creates a span using the global tracer. - * @ignore - * @param name The name of the operation being performed. - * @param tracingOptions The options for the underlying http request. + * @internal + * @hidden + * @param name - The name of the operation being performed. + * @param tracingOptions - The options for the underlying http request. */ export function createSpan( operationName: string, diff --git a/sdk/eventgrid/eventgrid/src/util.ts b/sdk/eventgrid/eventgrid/src/util.ts index 1ddc0f4bed59..79859bdc6253 100644 --- a/sdk/eventgrid/eventgrid/src/util.ts +++ b/sdk/eventgrid/eventgrid/src/util.ts @@ -14,7 +14,7 @@ import { KeyCredential } from "@azure/core-auth"; * * The service expects a UTC time, so this method returns a string based on the UTC time of the provided Date. * - * @param d The Date object to convert to a string. + * @param d - The Date object to convert to a string. */ export function dateToServiceTimeString(d: Date): string { const month = d.getUTCMonth() + 1; // getUTCMonth returns 0-11 not 1-12. @@ -39,7 +39,7 @@ export function dateToServiceTimeString(d: Date): string { * Returns `true` if the credential object is like the KeyCredential interface (i.e. it has a * key property). * - * @param credential the object to test + * @param credential - The object to test */ export function isKeyCredentialLike(o: unknown): o is KeyCredential { const castO = o as { diff --git a/sdk/eventgrid/eventgrid/tsdoc.json b/sdk/eventgrid/eventgrid/tsdoc.json new file mode 100644 index 000000000000..81c5a8a2aa2f --- /dev/null +++ b/sdk/eventgrid/eventgrid/tsdoc.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + "extends": ["../../../tsdoc.json"] +} diff --git a/sdk/formrecognizer/ai-form-recognizer/src/formRecognizerClient.ts b/sdk/formrecognizer/ai-form-recognizer/src/formRecognizerClient.ts index f05f7b82abf4..0d4d6ada0e69 100644 --- a/sdk/formrecognizer/ai-form-recognizer/src/formRecognizerClient.ts +++ b/sdk/formrecognizer/ai-form-recognizer/src/formRecognizerClient.ts @@ -205,7 +205,6 @@ export class FormRecognizerClient { /** * @internal - * @ignore * A reference to the auto-generated FormRecognizer HTTP client. */ private readonly client: GeneratedClient; @@ -223,9 +222,9 @@ export class FormRecognizerClient { * ); * ``` * - * @param {string} endpointUrl Url to an Azure Form Recognizer service endpoint - * @param {TokenCredential | KeyCredential} credential Used to authenticate requests to the service. - * @param {FormRecognizerClientOptions} [options] Used to configure the Form Recognizer client. + * @param endpointUrl - Url to an Azure Form Recognizer service endpoint + * @param credential - Used to authenticate requests to the service. + * @param options - Used to configure the Form Recognizer client. */ constructor( endpointUrl: string, @@ -287,9 +286,9 @@ export class FormRecognizerClient { * * const pages = await poller.pollUntilDone(); * ``` - * @summary Recognizes content/layout information from a given document - * @param {FormRecognizerRequestBody} form Input document - * @param {BeginRecognizeContentOptions} [options] Options to start content recognition operation + * Recognizes content/layout information from a given document + * @param form - Input document + * @param options - Options to start content recognition operation */ public async beginRecognizeContent( form: FormRecognizerRequestBody, @@ -330,9 +329,9 @@ export class FormRecognizerClient { * const pages = await poller.pollUntilDone(); * ``` * - * @summary Recognizes content/layout information from a url to a form document - * @param formUrl Url to a document that is accessible from the service. Must be a valid, encoded URL to a document of a supported content type. - * @param options Options for the content recognition operation + * Recognizes content/layout information from a url to a form document + * @param formUrl - Url to a document that is accessible from the service. Must be a valid, encoded URL to a document of a supported content type. + * @param options - Options for the content recognition operation */ public async beginRecognizeContentFromUrl( formUrl: string, @@ -360,7 +359,8 @@ export class FormRecognizerClient { /** * Retrieves result of content recognition operation. - * @private + * @internal + * @hidden */ private async getRecognizedContent( resultId: string, @@ -411,10 +411,10 @@ export class FormRecognizerClient { * }); * const forms = await poller.pollUntilDone(); * ``` - * @summary Recognizes form information from a given document using a custom form model. - * @param modelId Id of the custom form model to use - * @param form Input form document - * @param options Options to start the form recognition operation + * Recognizes form information from a given document using a custom form model. + * @param modelId - Id of the custom form model to use + * @param form - Input form document + * @param options - Options to start the form recognition operation */ public async beginRecognizeCustomForms( modelId: string, @@ -481,10 +481,10 @@ export class FormRecognizerClient { * const forms = await poller.pollUntilDone(); * ``` * - * @summary Recognizes form information from a url to a document using a custom form model. - * @param modelId Id of the custom form model to use - * @param formUrl Url to a document that is accessible from the service. Must be a valid, encoded URL to a document of a supported content type. - * @param options Options for the recognition operation + * Recognizes form information from a url to a document using a custom form model. + * @param modelId - Id of the custom form model to use + * @param formUrl - Url to a document that is accessible from the service. Must be a valid, encoded URL to a document of a supported content type. + * @param options - Options for the recognition operation */ public async beginRecognizeCustomFormsFromUrl( modelId: string, @@ -560,9 +560,9 @@ export class FormRecognizerClient { * const [businessCard] = await poller.pollUntilDone(); * ``` * - * @summary Recognizes business card information from a given document - * @param businessCard Input document - * @param options Options for the recognition operation + * Recognizes business card information from a given document + * @param businessCard - Input document + * @param options - Options for the recognition operation */ public async beginRecognizeBusinessCards( businessCard: FormRecognizerRequestBody, @@ -624,9 +624,9 @@ export class FormRecognizerClient { * const [businessCard] = await poller.pollUntilDone(); * ``` * - * @summary Recognizes business card information from a given accessible url to a document - * @param businessCardUrl Url to a business card document that is accessible from the service. Must be a valid, encoded URL to a document of a supported content type. - * @param options Options for the recognition operation + * Recognizes business card information from a given accessible url to a document + * @param businessCardUrl - Url to a business card document that is accessible from the service. Must be a valid, encoded URL to a document of a supported content type. + * @param options - Options for the recognition operation */ public async beginRecognizeBusinessCardsFromUrl( businessCardUrl: string, @@ -697,9 +697,9 @@ export class FormRecognizerClient { * const [invoice] = await poller.pollUntilDone(); * ``` * - * @summary Recognizes invoice information from a given document - * @param invoice Input document - * @param options Options for the recognition operation + * Recognizes invoice information from a given document + * @param invoice - Input document + * @param options - Options for the recognition operation */ public async beginRecognizeInvoices( invoice: FormRecognizerRequestBody, @@ -761,9 +761,9 @@ export class FormRecognizerClient { * const [invoice] = await poller.pollUntilDone(); * ``` * - * @summary Recognizes invoice information from a given accessible url to a document - * @param invoiceUrl Url to an invoice document that is accessible from the service. Must be a valid, encoded URL to a document of a supported content type. - * @param options Options for the recognition operation + * Recognizes invoice information from a given accessible url to a document + * @param invoiceUrl - Url to an invoice document that is accessible from the service. Must be a valid, encoded URL to a document of a supported content type. + * @param options - Options for the recognition operation */ public async beginRecognizeInvoicesFromUrl( invoiceUrl: string, @@ -834,9 +834,9 @@ export class FormRecognizerClient { * const [receipt] = await poller.pollUntilDone(); * ``` * - * @summary Recognizes receipt information from a given document - * @param receipt Input document - * @param options Options for the recognition operation + * Recognizes receipt information from a given document + * @param receipt - Input document + * @param options - Options for the recognition operation */ public async beginRecognizeReceipts( receipt: FormRecognizerRequestBody, @@ -899,9 +899,9 @@ export class FormRecognizerClient { * const [receipt] = await poller.pollUntilDone(); * ``` * - * @summary Recognizes receipt information from a given accessible url to a document - * @param receiptUrl Url to a receipt document that is accessible from the service. Must be a valid, encoded URL to a document of a supported content type. - * @param options Options for the recognition operation + * Recognizes receipt information from a given accessible url to a document + * @param receiptUrl - Url to a receipt document that is accessible from the service. Must be a valid, encoded URL to a document of a supported content type. + * @param options - Options for the recognition operation */ public async beginRecognizeReceiptsFromUrl( receiptUrl: string, @@ -958,8 +958,8 @@ interface RemoteOperation { * Validates a remote operation's location is defined and extracts the * result ID from it. * - * @param remoteOperation the operation to process - * @returns the remote operation ID + * @param remoteOperation - The operation to process + * @returns The remote operation ID * * @internal */ @@ -983,11 +983,11 @@ interface Spanner { * an argument will be inserted at the beginning of the arguments list * containing the `options` that may have been updated by the tracer. * - * @param name the name of this span, which will appear in the trace. - * @param handler the handler to run. Its first parameter will have the + * @param name - The name of this span, which will appear in the trace. + * @param handler - The handler to run. Its first parameter will have the * type of `options` that were passed to `makeSpanner` * - * @returns a function that will wrap a call to the `handler` in tracing code, forwarding its parameters + * @returns A function that will wrap a call to the `handler` in tracing code, forwarding its parameters */ span( name: string, diff --git a/sdk/formrecognizer/ai-form-recognizer/src/formTrainingClient.ts b/sdk/formrecognizer/ai-form-recognizer/src/formTrainingClient.ts index 117f91dd6dc2..f1a7526fd503 100644 --- a/sdk/formrecognizer/ai-form-recognizer/src/formTrainingClient.ts +++ b/sdk/formrecognizer/ai-form-recognizer/src/formTrainingClient.ts @@ -177,19 +177,19 @@ export class FormTrainingClient { /** * @internal - * @ignore + * @hidden */ private readonly credential: TokenCredential | KeyCredential; /** * @internal - * @ignore + * @hidden */ private readonly clientOptions: FormRecognizerClientOptions; /** * @internal - * @ignore + * @hidden * A reference to the auto-generated FormRecognizer HTTP client. */ private readonly client: GeneratedClient; @@ -206,9 +206,9 @@ export class FormTrainingClient { * new AzureKeyCredential("") * ); * ``` - * @param {string} endpointUrl Url to an Azure Form Recognizer service endpoint - * @param {TokenCredential | KeyCredential} credential Used to authenticate requests to the service. - * @param {FormRecognizerClientOptions} [options] Used to configure the client. + * @param endpointUrl - Url to an Azure Form Recognizer service endpoint + * @param credential - Used to authenticate requests to the service. + * @param options - Used to configure the client. */ constructor( endpointUrl: string, @@ -253,7 +253,7 @@ export class FormTrainingClient { /** * Retrieves summary information about the cognitive service account * - * @param {GetAccountPropertiesOptions} options Options to GetSummary operation + * @param options - Options to GetSummary operation */ public async getAccountProperties( options?: GetAccountPropertiesOptions @@ -295,8 +295,8 @@ export class FormTrainingClient { /** * Mark model for deletion. Model artifacts will be permanently removed within 48 hours. * - * @param {string} modelId Id of the model to mark for deletion - * @param {DeleteModelOptions} options Options to the Delete Model operation + * @param modelId - Id of the model to mark for deletion + * @param options - Options to the Delete Model operation */ public async deleteModel(modelId: string, options?: DeleteModelOptions): Promise { const realOptions = options || {}; @@ -324,8 +324,8 @@ export class FormTrainingClient { /** * Get detailed information about a custom model from training. * - * @param {string} modelId Id of the model to get information - * @param {GetModelOptions} options Options to the Get Model operation + * @param modelId - Id of the model to get information + * @param options - Options to the Get Model operation */ public async getCustomModel( modelId: string, @@ -423,7 +423,7 @@ export class FormTrainingClient { * } * ``` * - * @param {ListModelOptions} options Options to the List Models operation + * @param options - Options to the List Models operation */ public listCustomModels( options: ListModelsOptions = {} @@ -525,10 +525,10 @@ export class FormTrainingClient { * const model = await poller.pollUntilDone(); * ``` * - * @summary Creates and trains a custom form model. - * @param trainingFilesUrl accessible url to an Azure Storage Blob container storing the training documents and optional label files - * @param useTrainingLabels specifies whether or not to search for and train using label files - * @param options options to start the model training operation + * Creates and trains a custom form model. + * @param trainingFilesUrl - Accessible url to an Azure Storage Blob container storing the training documents and optional label files + * @param useTrainingLabels - Specifies whether or not to search for and train using label files + * @param options - Options to start the model training operation */ public async beginTraining( trainingFilesUrl: string, @@ -588,9 +588,9 @@ export class FormTrainingClient { * const composedModel = await poller.pollUntilDone(); * ``` * - * @summary Combines pre-existing models with labels into a single composed model. - * @param modelIds an array of model IDs within the Form Recognizer resouce to compose - * @param options Options to start the create composed model operation + * Combines pre-existing models with labels into a single composed model. + * @param modelIds - An array of model IDs within the Form Recognizer resouce to compose + * @param options - Options to start the create composed model operation */ public async beginCreateComposedModel( modelIds: string[], @@ -627,10 +627,10 @@ export class FormTrainingClient { * * The required `resourceId` and `resourceRegion` are properties of an Azure Form Recognizer resource and their values can be found in the Azure Portal. * - * @param {string} resourceId Id of the Azure Form Recognizer resource where a custom model will be copied to - * @param {string} resourceRegion Location of the Azure Form Recognizer resource, must be a valid region name supported by Azure Cognitive Services. See https://aka.ms/azsdk/cognitiveservices/regionalavailability for information about the regional availability of Azure Cognitive Services. - * @param {GetCopyAuthorizationOptions} [options={}] Options to get copy authorization operation - * @returns {Promise} The authorization to copy a custom model + * @param resourceId - Id of the Azure Form Recognizer resource where a custom model will be copied to + * @param resourceRegion - Location of the Azure Form Recognizer resource, must be a valid region name supported by Azure Cognitive Services. See https://aka.ms/azsdk/cognitiveservices/regionalavailability for information about the regional availability of Azure Cognitive Services. + * @param options - Options to get copy authorization operation + * @returns The authorization to copy a custom model */ public async getCopyAuthorization( resourceId: string, @@ -684,10 +684,10 @@ export class FormTrainingClient { * }); * const result = await poller.pollUntilDone(); * ``` - * @summary Copies custom model to target resource - * @param {string} modelId Id of the custom model in this resource to be copied to the target Form Recognizer resource - * @param {CopyAuthorization} target Copy authorization produced by calling `targetTrainingClient.getCopyAuthorization()` - * @param {BeginTrainingOptions} [options] Options to copy model operation + * Copies custom model to target resource + * @param modelId - Id of the custom model in this resource to be copied to the target Form Recognizer resource + * @param target - Copy authorization produced by calling `targetTrainingClient.getCopyAuthorization()` + * @param options - Options to copy model operation */ public async beginCopyModel( modelId: string, diff --git a/sdk/formrecognizer/ai-form-recognizer/src/logger.ts b/sdk/formrecognizer/ai-form-recognizer/src/logger.ts index b27347019c50..660d6424e827 100644 --- a/sdk/formrecognizer/ai-form-recognizer/src/logger.ts +++ b/sdk/formrecognizer/ai-form-recognizer/src/logger.ts @@ -4,6 +4,6 @@ import { createClientLogger } from "@azure/logger"; /** - * The @azure/logger configuration for this package. + * The \@azure/logger configuration for this package. */ export const logger = createClientLogger("ai-form-recognizer"); diff --git a/sdk/formrecognizer/ai-form-recognizer/src/lro/analyze/contentPoller.ts b/sdk/formrecognizer/ai-form-recognizer/src/lro/analyze/contentPoller.ts index 0919c21cee10..d5696de6ef07 100644 --- a/sdk/formrecognizer/ai-form-recognizer/src/lro/analyze/contentPoller.ts +++ b/sdk/formrecognizer/ai-form-recognizer/src/lro/analyze/contentPoller.ts @@ -123,7 +123,8 @@ export class BeginRecognizeContentPoller extends Poller< } /** * Creates a poll operation given the provided state. - * @ignore + * @internal + * @hidden */ function makeBeginRecognizePollOperation( state: BeginRecognizeContentPollState diff --git a/sdk/formrecognizer/ai-form-recognizer/src/lro/copy/poller.ts b/sdk/formrecognizer/ai-form-recognizer/src/lro/copy/poller.ts index 1a0a85d422d9..eae1700b992d 100644 --- a/sdk/formrecognizer/ai-form-recognizer/src/lro/copy/poller.ts +++ b/sdk/formrecognizer/ai-form-recognizer/src/lro/copy/poller.ts @@ -158,7 +158,8 @@ export class BeginCopyModelPoller extends Poller( operationName: string, diff --git a/sdk/formrecognizer/ai-form-recognizer/src/utils/utils.node.ts b/sdk/formrecognizer/ai-form-recognizer/src/utils/utils.node.ts index 63db206290c2..fadeb16eeea5 100644 --- a/sdk/formrecognizer/ai-form-recognizer/src/utils/utils.node.ts +++ b/sdk/formrecognizer/ai-form-recognizer/src/utils/utils.node.ts @@ -7,10 +7,9 @@ const SIZE_ONE_MEGA = 1024 * 1024; * Reads a readable stream into buffer entirely. NodeJS only. * The maximum allowed size is specified in {@link MAX_INPUT_DOCUMENT_SIZE}. * - * @export - * @param {NodeJS.ReadableStream} stream A Node.js Readable stream - * @returns {Promise} The resultant buffer. - * @throws {Error} If buffer size is not big enough. + * @param stream - A Node.js Readable stream + * @returns The resultant buffer. + * @throws If buffer size is not big enough. */ export async function streamToBuffer( stream: NodeJS.ReadableStream, diff --git a/sdk/formrecognizer/ai-form-recognizer/test/utils/matrix.ts b/sdk/formrecognizer/ai-form-recognizer/test/utils/matrix.ts index 818715af0c2e..a2dbac744e1e 100644 --- a/sdk/formrecognizer/ai-form-recognizer/test/utils/matrix.ts +++ b/sdk/formrecognizer/ai-form-recognizer/test/utils/matrix.ts @@ -2,15 +2,17 @@ // Licensed under the MIT license. /** + * @internal + * @hidden * Takes a jagged 2D array and a function and runs the function with every * possible combination of elements of each of the arrays * * For strong type-checking, it is important that the `matrix` have a strong * type, such as a `const` literal. * - * @param values jagged 2D array specifying the arguments and their possible - * values - * @param handler the function to run with the different argument combinations + * @param values - jagged 2D array specifying the arguments and their possible + * values + * @param handler - the function to run with the different argument combinations * * @example * ```typescript diff --git a/sdk/formrecognizer/ai-form-recognizer/tsdoc.json b/sdk/formrecognizer/ai-form-recognizer/tsdoc.json new file mode 100644 index 000000000000..81c5a8a2aa2f --- /dev/null +++ b/sdk/formrecognizer/ai-form-recognizer/tsdoc.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + "extends": ["../../../tsdoc.json"] +} diff --git a/sdk/identity/identity/src/client/errors.ts b/sdk/identity/identity/src/client/errors.ts index ad5afe83e5b6..af15169ed8fc 100644 --- a/sdk/identity/identity/src/client/errors.ts +++ b/sdk/identity/identity/src/client/errors.ts @@ -44,7 +44,7 @@ export interface ErrorResponse { /** * Used for internal deserialization of OAuth responses. Public model is ErrorResponse * @internal - * @ignore + * @hidden */ export interface OAuthErrorResponse { error: string; diff --git a/sdk/identity/identity/src/client/msalClient.ts b/sdk/identity/identity/src/client/msalClient.ts index e84d222e81a6..a86414868924 100644 --- a/sdk/identity/identity/src/client/msalClient.ts +++ b/sdk/identity/identity/src/client/msalClient.ts @@ -161,8 +161,8 @@ export class HttpClient implements INetworkModule { /** * Http Get request - * @param url - * @param options + * @param url - + * @param options - */ async sendGetRequestAsync( url: string, @@ -185,8 +185,8 @@ export class HttpClient implements INetworkModule { /** * Http Post request - * @param url - * @param options + * @param url - + * @param options - */ async sendPostRequestAsync( url: string, diff --git a/sdk/identity/identity/src/constants.ts b/sdk/identity/identity/src/constants.ts index 1d5382e89d8a..df504175cbb4 100644 --- a/sdk/identity/identity/src/constants.ts +++ b/sdk/identity/identity/src/constants.ts @@ -4,7 +4,7 @@ /** * The default client ID for authentication * @internal - * @ignore + * @hidden */ // TODO: temporary - this is the Azure CLI clientID - we'll replace it when // Developer Sign On application is available @@ -14,7 +14,7 @@ export const DeveloperSignOnClientId = "04b07795-8ddb-461a-bbee-02f9e1bf7b46"; /** * The default tenant for authentication * @internal - * @ignore + * @hidden */ export const DefaultTenantId = "common"; diff --git a/sdk/identity/identity/src/credentials/authorizationCodeCredential.ts b/sdk/identity/identity/src/credentials/authorizationCodeCredential.ts index 8ea270ac6e75..865c8134ad81 100644 --- a/sdk/identity/identity/src/credentials/authorizationCodeCredential.ts +++ b/sdk/identity/identity/src/credentials/authorizationCodeCredential.ts @@ -40,16 +40,16 @@ export class AuthorizationCodeCredential implements TokenCredential { * * https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/identity/identity/samples/authorizationCodeSample.ts * - * @param tenantId The Azure Active Directory tenant (directory) ID or name. + * @param tenantId - The Azure Active Directory tenant (directory) ID or name. * 'common' may be used when dealing with multi-tenant scenarios. - * @param clientId The client (application) ID of an App Registration in the tenant. - * @param clientSecret A client secret that was generated for the App Registration - * @param authorizationCode An authorization code that was received from following the + * @param clientId - The client (application) ID of an App Registration in the tenant. + * @param clientSecret - A client secret that was generated for the App Registration + * @param authorizationCode - An authorization code that was received from following the authorization code flow. This authorization code must not have already been used to obtain an access token. - * @param redirectUri The redirect URI that was used to request the authorization code. + * @param redirectUri - The redirect URI that was used to request the authorization code. Must be the same URI that is configured for the App Registration. - * @param options Options for configuring the client which makes the access token request. + * @param options - Options for configuring the client which makes the access token request. */ constructor( tenantId: string | "common", @@ -70,15 +70,15 @@ export class AuthorizationCodeCredential implements TokenCredential { * * https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/identity/identity/samples/authorizationCodeSample.ts * - * @param tenantId The Azure Active Directory tenant (directory) ID or name. + * @param tenantId - The Azure Active Directory tenant (directory) ID or name. * 'common' may be used when dealing with multi-tenant scenarios. - * @param clientId The client (application) ID of an App Registration in the tenant. - * @param authorizationCode An authorization code that was received from following the + * @param clientId - The client (application) ID of an App Registration in the tenant. + * @param authorizationCode - An authorization code that was received from following the authorization code flow. This authorization code must not have already been used to obtain an access token. - * @param redirectUri The redirect URI that was used to request the authorization code. + * @param redirectUri - The redirect URI that was used to request the authorization code. Must be the same URI that is configured for the App Registration. - * @param options Options for configuring the client which makes the access token request. + * @param options - Options for configuring the client which makes the access token request. */ constructor( tenantId: string | "common", @@ -88,7 +88,7 @@ export class AuthorizationCodeCredential implements TokenCredential { options?: TokenCredentialOptions ); /** - * @ignore + * @hidden * @internal */ constructor( @@ -127,8 +127,8 @@ export class AuthorizationCodeCredential implements TokenCredential { * return null. If an error occurs during authentication, an {@link AuthenticationError} * containing failure details will be thrown. * - * @param scopes The list of scopes for which the token will have access. - * @param options The options used to configure any requests this + * @param scopes - The list of scopes for which the token will have access. + * @param options - The options used to configure any requests this * TokenCredential implementation might make. */ public async getToken( diff --git a/sdk/identity/identity/src/credentials/azureCliCredential.ts b/sdk/identity/identity/src/credentials/azureCliCredential.ts index f740bc1bbb32..9302e91e9e12 100644 --- a/sdk/identity/identity/src/credentials/azureCliCredential.ts +++ b/sdk/identity/identity/src/credentials/azureCliCredential.ts @@ -32,7 +32,7 @@ const logger = credentialLogger("AzureCliCredential"); export class AzureCliCredential implements TokenCredential { /** * Gets the access token from Azure CLI - * @param resource The resource to use when getting the token + * @param resource - The resource to use when getting the token */ protected async getAzureCliAccessToken( resource: string @@ -58,8 +58,8 @@ export class AzureCliCredential implements TokenCredential { * return null. If an error occurs during authentication, an {@link AuthenticationError} * containing failure details will be thrown. * - * @param scopes The list of scopes for which the token will have access. - * @param options The options used to configure any requests this + * @param scopes - The list of scopes for which the token will have access. + * @param options - The options used to configure any requests this * TokenCredential implementation might make. */ public async getToken( diff --git a/sdk/identity/identity/src/credentials/chainedTokenCredential.ts b/sdk/identity/identity/src/credentials/chainedTokenCredential.ts index e606e8d5b505..092946f2ab55 100644 --- a/sdk/identity/identity/src/credentials/chainedTokenCredential.ts +++ b/sdk/identity/identity/src/credentials/chainedTokenCredential.ts @@ -25,7 +25,7 @@ export class ChainedTokenCredential implements TokenCredential { /** * Creates an instance of ChainedTokenCredential using the given credentials. * - * @param sources `TokenCredential` implementations to be tried in order. + * @param sources - `TokenCredential` implementations to be tried in order. * * Example usage: * ```javascript @@ -47,8 +47,8 @@ export class ChainedTokenCredential implements TokenCredential { * This method is called automatically by Azure SDK client libraries. You may call this method * directly, but you must also handle token caching and token refreshing. * - * @param scopes The list of scopes for which the token will have access. - * @param options The options used to configure any requests this + * @param scopes - The list of scopes for which the token will have access. + * @param options - The options used to configure any requests this * `TokenCredential` implementation might make. */ async getToken( diff --git a/sdk/identity/identity/src/credentials/clientCertificateCredential.ts b/sdk/identity/identity/src/credentials/clientCertificateCredential.ts index d368cac22751..38c1b1f43ffa 100644 --- a/sdk/identity/identity/src/credentials/clientCertificateCredential.ts +++ b/sdk/identity/identity/src/credentials/clientCertificateCredential.ts @@ -50,10 +50,10 @@ export class ClientCertificateCredential implements TokenCredential { * Creates an instance of the ClientCertificateCredential with the details * needed to authenticate against Azure Active Directory with a certificate. * - * @param tenantId The Azure Active Directory tenant (directory) ID. - * @param clientId The client (application) ID of an App Registration in the tenant. - * @param certificatePath The path to a PEM-encoded public/private key certificate on the filesystem. - * @param options Options for configuring the client which makes the authentication request. + * @param tenantId - The Azure Active Directory tenant (directory) ID. + * @param clientId - The client (application) ID of an App Registration in the tenant. + * @param certificatePath - The path to a PEM-encoded public/private key certificate on the filesystem. + * @param options - Options for configuring the client which makes the authentication request. */ constructor( tenantId: string, @@ -106,8 +106,8 @@ export class ClientCertificateCredential implements TokenCredential { * return null. If an error occurs during authentication, an {@link AuthenticationError} * containing failure details will be thrown. * - * @param scopes The list of scopes for which the token will have access. - * @param options The options used to configure any requests this + * @param scopes - The list of scopes for which the token will have access. + * @param options - The options used to configure any requests this * TokenCredential implementation might make. */ public async getToken( diff --git a/sdk/identity/identity/src/credentials/clientSecretCredential.ts b/sdk/identity/identity/src/credentials/clientSecretCredential.ts index 0ff52a238d48..a7d1382d9b7f 100644 --- a/sdk/identity/identity/src/credentials/clientSecretCredential.ts +++ b/sdk/identity/identity/src/credentials/clientSecretCredential.ts @@ -31,10 +31,10 @@ export class ClientSecretCredential implements TokenCredential { * needed to authenticate against Azure Active Directory with a client * secret. * - * @param tenantId The Azure Active Directory tenant (directory) ID. - * @param clientId The client (application) ID of an App Registration in the tenant. - * @param clientSecret A client secret that was generated for the App Registration. - * @param options Options for configuring the client which makes the authentication request. + * @param tenantId - The Azure Active Directory tenant (directory) ID. + * @param clientId - The client (application) ID of an App Registration in the tenant. + * @param clientSecret - A client secret that was generated for the App Registration. + * @param options - Options for configuring the client which makes the authentication request. */ constructor( tenantId: string, @@ -54,8 +54,8 @@ export class ClientSecretCredential implements TokenCredential { * return null. If an error occurs during authentication, an {@link AuthenticationError} * containing failure details will be thrown. * - * @param scopes The list of scopes for which the token will have access. - * @param options The options used to configure any requests this + * @param scopes - The list of scopes for which the token will have access. + * @param options - The options used to configure any requests this * TokenCredential implementation might make. */ public async getToken( diff --git a/sdk/identity/identity/src/credentials/defaultAzureCredential.browser.ts b/sdk/identity/identity/src/credentials/defaultAzureCredential.browser.ts index c6f7eb6f1212..f7b9692cf91e 100644 --- a/sdk/identity/identity/src/credentials/defaultAzureCredential.browser.ts +++ b/sdk/identity/identity/src/credentials/defaultAzureCredential.browser.ts @@ -23,7 +23,7 @@ export class DefaultAzureCredential extends ChainedTokenCredential { /** * Creates an instance of the DefaultAzureCredential class. * - * @param options Options for configuring the client which makes the authentication request. + * @param options - Options for configuring the client which makes the authentication request. */ constructor(tokenCredentialOptions?: TokenCredentialOptions) { const credentials = []; diff --git a/sdk/identity/identity/src/credentials/defaultAzureCredential.ts b/sdk/identity/identity/src/credentials/defaultAzureCredential.ts index b308cf8cf957..6641f4d1b23c 100644 --- a/sdk/identity/identity/src/credentials/defaultAzureCredential.ts +++ b/sdk/identity/identity/src/credentials/defaultAzureCredential.ts @@ -37,7 +37,7 @@ export class DefaultAzureCredential extends ChainedTokenCredential { /** * Creates an instance of the DefaultAzureCredential class. * - * @param options Options for configuring the client which makes the authentication request. + * @param options - Options for configuring the client which makes the authentication request. */ constructor(tokenCredentialOptions?: DefaultAzureCredentialOptions) { const credentials = []; diff --git a/sdk/identity/identity/src/credentials/deviceCodeCredential.ts b/sdk/identity/identity/src/credentials/deviceCodeCredential.ts index 8d1707190ac5..f5f5fd14d216 100644 --- a/sdk/identity/identity/src/credentials/deviceCodeCredential.ts +++ b/sdk/identity/identity/src/credentials/deviceCodeCredential.ts @@ -47,7 +47,7 @@ const logger = credentialLogger("DeviceCodeCredential"); /** * Method that logs the user code from the DeviceCodeCredential. - * @param deviceCodeInfo The device code. + * @param deviceCodeInfo - The device code. */ export function defaultDeviceCodePromptCallback(deviceCodeInfo: DeviceCodeInfo): void { console.log(deviceCodeInfo.message); @@ -65,14 +65,14 @@ export class DeviceCodeCredential implements TokenCredential { * Creates an instance of DeviceCodeCredential with the details needed * to initiate the device code authorization flow with Azure Active Directory. * - * @param tenantId The Azure Active Directory tenant (directory) ID or name. - * The default value is 'organizations'. - * 'organizations' may be used when dealing with multi-tenant scenarios. - * @param clientId The client (application) ID of an App Registration in the tenant. - * By default we will try to use the Azure CLI's client ID to authenticate. - * @param userPromptCallback A callback function that will be invoked to show + * @param tenantId - The Azure Active Directory tenant (directory) ID or name. + * The default value is 'organizations'. + * 'organizations' may be used when dealing with multi-tenant scenarios. + * @param clientId - The client (application) ID of an App Registration in the tenant. + * By default we will try to use the Azure CLI's client ID to authenticate. + * @param userPromptCallback - A callback function that will be invoked to show {@link DeviceCodeInfo} to the user. If left unassigned, we will automatically log the device code information and the authentication instructions in the console. - * @param options Options for configuring the client which makes the authentication request. + * @param options - Options for configuring the client which makes the authentication request. */ constructor( tenantId: string = "organizations", @@ -109,8 +109,8 @@ export class DeviceCodeCredential implements TokenCredential { * return null. If an error occurs during authentication, an {@link AuthenticationError} * containing failure details will be thrown. * - * @param scopes The list of scopes for which the token will have access. - * @param options The options used to configure any requests this + * @param scopes - The list of scopes for which the token will have access. + * @param options - The options used to configure any requests this * TokenCredential implementation might make. */ async getToken( diff --git a/sdk/identity/identity/src/credentials/environmentCredential.ts b/sdk/identity/identity/src/credentials/environmentCredential.ts index 0c1dc69068ef..7ce0b6230ef8 100644 --- a/sdk/identity/identity/src/credentials/environmentCredential.ts +++ b/sdk/identity/identity/src/credentials/environmentCredential.ts @@ -54,7 +54,7 @@ export class EnvironmentCredential implements TokenCredential { * environment variables are not found at this time, the getToken method * will return null when invoked. * - * @param options Options for configuring the client which makes the authentication request. + * @param options - Options for configuring the client which makes the authentication request. */ constructor(options?: TokenCredentialOptions) { // Keep track of any missing environment variables for error details @@ -114,8 +114,8 @@ export class EnvironmentCredential implements TokenCredential { * return null. If an error occurs during authentication, an {@link AuthenticationError} * containing failure details will be thrown. * - * @param scopes The list of scopes for which the token will have access. - * @param options The options used to configure any requests this + * @param scopes - The list of scopes for which the token will have access. + * @param options - The options used to configure any requests this * TokenCredential implementation might make. */ async getToken( diff --git a/sdk/identity/identity/src/credentials/interactiveBrowserCredential.browser.ts b/sdk/identity/identity/src/credentials/interactiveBrowserCredential.browser.ts index f850d6cf1336..27a963bd63ac 100644 --- a/sdk/identity/identity/src/credentials/interactiveBrowserCredential.browser.ts +++ b/sdk/identity/identity/src/credentials/interactiveBrowserCredential.browser.ts @@ -30,9 +30,9 @@ export class InteractiveBrowserCredential implements TokenCredential { * details needed to authenticate against Azure Active Directory with * a user identity. * - * @param tenantId The Azure Active Directory tenant (directory) ID. - * @param clientId The client (application) ID of an App Registration in the tenant. - * @param options Options for configuring the client which makes the authentication request. + * @param tenantId - The Azure Active Directory tenant (directory) ID. + * @param clientId - The client (application) ID of an App Registration in the tenant. + * @param options - Options for configuring the client which makes the authentication request. */ constructor(options?: InteractiveBrowserCredentialOptions) { options = { @@ -137,9 +137,9 @@ export class InteractiveBrowserCredential implements TokenCredential { * return null. If an error occurs during authentication, an {@link AuthenticationError} * containing failure details will be thrown. * - * @param scopes The list of scopes for which the token will have access. - * @param options The options used to configure any requests this - * TokenCredential implementation might make. + * @param scopes - The list of scopes for which the token will have access. + * @param options - The options used to configure any requests this + * TokenCredential implementation might make. */ async getToken( scopes: string | string[], diff --git a/sdk/identity/identity/src/credentials/interactiveBrowserCredential.ts b/sdk/identity/identity/src/credentials/interactiveBrowserCredential.ts index 88afaaff5448..9f13913ce529 100644 --- a/sdk/identity/identity/src/credentials/interactiveBrowserCredential.ts +++ b/sdk/identity/identity/src/credentials/interactiveBrowserCredential.ts @@ -78,9 +78,9 @@ export class InteractiveBrowserCredential implements TokenCredential { * return null. If an error occurs during authentication, an {@link AuthenticationError} * containing failure details will be thrown. * - * @param scopes The list of scopes for which the token will have access. - * @param options The options used to configure any requests this - * TokenCredential implementation might make. + * @param scopes - The list of scopes for which the token will have access. + * @param options - The options used to configure any requests this + * TokenCredential implementation might make. */ public getToken( scopes: string | string[], diff --git a/sdk/identity/identity/src/credentials/managedIdentityCredential/index.ts b/sdk/identity/identity/src/credentials/managedIdentityCredential/index.ts index 163cfcd0e414..58ecfef907a4 100644 --- a/sdk/identity/identity/src/credentials/managedIdentityCredential/index.ts +++ b/sdk/identity/identity/src/credentials/managedIdentityCredential/index.ts @@ -38,19 +38,19 @@ export class ManagedIdentityCredential implements TokenCredential { * Creates an instance of ManagedIdentityCredential with the client ID of a * user-assigned identity. * - * @param clientId The client ID of the user-assigned identity. - * @param options Options for configuring the client which makes the access token request. + * @param clientId - The client ID of the user-assigned identity. + * @param options - Options for configuring the client which makes the access token request. */ constructor(clientId: string, options?: TokenCredentialOptions); /** * Creates an instance of ManagedIdentityCredential * - * @param options Options for configuring the client which makes the access token request. + * @param options - Options for configuring the client which makes the access token request. */ constructor(options?: TokenCredentialOptions); /** * @internal - * @ignore + * @hidden */ constructor( clientIdOrOptions: string | TokenCredentialOptions | undefined, @@ -128,8 +128,8 @@ export class ManagedIdentityCredential implements TokenCredential { * return null. If an error occurs during authentication, an {@link AuthenticationError} * containing failure details will be thrown. * - * @param scopes The list of scopes for which the token will have access. - * @param options The options used to configure any requests this + * @param scopes - The list of scopes for which the token will have access. + * @param options - The options used to configure any requests this * TokenCredential implementation might make. */ public async getToken( diff --git a/sdk/identity/identity/src/credentials/usernamePasswordCredential.ts b/sdk/identity/identity/src/credentials/usernamePasswordCredential.ts index 80aed049920e..7bf1ac2bdacd 100644 --- a/sdk/identity/identity/src/credentials/usernamePasswordCredential.ts +++ b/sdk/identity/identity/src/credentials/usernamePasswordCredential.ts @@ -31,11 +31,11 @@ export class UsernamePasswordCredential implements TokenCredential { * needed to authenticate against Azure Active Directory with a username * and password. * - * @param tenantIdOrName The Azure Active Directory tenant (directory) ID or name. - * @param clientId The client (application) ID of an App Registration in the tenant. - * @param username The user account's e-mail address (user name). - * @param password The user account's account password - * @param options Options for configuring the client which makes the authentication request. + * @param tenantIdOrName - The Azure Active Directory tenant (directory) ID or name. + * @param clientId - The client (application) ID of an App Registration in the tenant. + * @param username - The user account's e-mail address (user name). + * @param password - The user account's account password + * @param options - Options for configuring the client which makes the authentication request. */ constructor( tenantIdOrName: string, @@ -59,8 +59,8 @@ export class UsernamePasswordCredential implements TokenCredential { * return null. If an error occurs during authentication, an {@link AuthenticationError} * containing failure details will be thrown. * - * @param scopes The list of scopes for which the token will have access. - * @param options The options used to configure any requests this + * @param scopes - The list of scopes for which the token will have access. + * @param options - The options used to configure any requests this * TokenCredential implementation might make. */ public async getToken( diff --git a/sdk/identity/identity/src/credentials/visualStudioCodeCredential.ts b/sdk/identity/identity/src/credentials/visualStudioCodeCredential.ts index 904a9ddb085f..d63d04e45172 100644 --- a/sdk/identity/identity/src/credentials/visualStudioCodeCredential.ts +++ b/sdk/identity/identity/src/credentials/visualStudioCodeCredential.ts @@ -104,7 +104,7 @@ export class VisualStudioCodeCredential implements TokenCredential { /** * Creates an instance of VisualStudioCodeCredential to use for automatically authenticating via VSCode. * - * @param options Options for configuring the client which makes the authentication request. + * @param options - Options for configuring the client which makes the authentication request. */ constructor(options?: VisualStudioCodeCredentialOptions) { // We want to make sure we use the one assigned by the user on the VSCode settings. @@ -161,8 +161,8 @@ export class VisualStudioCodeCredential implements TokenCredential { * Returns the token found by searching VSCode's authentication cache or * returns null if no token could be found. * - * @param scopes The list of scopes for which the token will have access. - * @param options The options used to configure any requests this + * @param scopes - The list of scopes for which the token will have access. + * @param options - The options used to configure any requests this * `TokenCredential` implementation might make. */ public async getToken( diff --git a/sdk/identity/identity/src/util/logging.ts b/sdk/identity/identity/src/util/logging.ts index 521039e89c47..e4e8398e497d 100644 --- a/sdk/identity/identity/src/util/logging.ts +++ b/sdk/identity/identity/src/util/logging.ts @@ -15,7 +15,7 @@ interface EnvironmentAccumulator { /** * Separates a list of environment variable names into a plain object with two arrays: an array of missing environment variables and another array with assigned environment variables. - * @param supportedEnvVars List of environment variable names + * @param supportedEnvVars - List of environment variable names */ export function processEnvVars(supportedEnvVars: string[]): EnvironmentAccumulator { return supportedEnvVars.reduce( @@ -34,8 +34,8 @@ export function processEnvVars(supportedEnvVars: string[]): EnvironmentAccumulat /** * Based on a given list of environment variable names, * logs the environment variables currently assigned during the usage of a credential that goes by the given name. - * @param credentialName Name of the credential in use - * @param supportedEnvVars List of environment variables supported by that credential + * @param credentialName - Name of the credential in use + * @param supportedEnvVars - List of environment variables supported by that credential */ export function logEnvVars(credentialName: string, supportedEnvVars: string[]): void { const { assigned } = processEnvVars(supportedEnvVars); @@ -83,7 +83,7 @@ export interface CredentialLoggerInstance { * * It logs with the format: * - * [title] => [message] + * `[title] => [message]` * */ export function credentialLoggerInstance( @@ -118,8 +118,8 @@ export interface CredentialLogger extends CredentialLoggerInstance { * * It logs with the format: * - * [title] => [message] - * [title] => getToken() => [message] + * `[title] => [message]` + * `[title] => getToken() => [message]` * */ export function credentialLogger(title: string, log: AzureLogger = logger): CredentialLogger { diff --git a/sdk/identity/identity/src/util/tracing.ts b/sdk/identity/identity/src/util/tracing.ts index 3471a49495ff..173f43f04870 100644 --- a/sdk/identity/identity/src/util/tracing.ts +++ b/sdk/identity/identity/src/util/tracing.ts @@ -7,8 +7,8 @@ import { Span, SpanKind, SpanOptions as OTSpanOptions } from "@opentelemetry/api /** * Creates a span using the global tracer. - * @param name The name of the operation being performed. - * @param options The options for the underlying http request. + * @param name - The name of the operation being performed. + * @param options - The options for the underlying http request. */ export function createSpan( operationName: string, diff --git a/sdk/identity/identity/test/mockAzureCliCredentialClient.ts b/sdk/identity/identity/test/mockAzureCliCredentialClient.ts index 222b378ca5bb..58bbbdeeb67b 100644 --- a/sdk/identity/identity/test/mockAzureCliCredentialClient.ts +++ b/sdk/identity/identity/test/mockAzureCliCredentialClient.ts @@ -22,7 +22,7 @@ export class MockAzureCliCredentialClient extends AzureCliCredential { * Replace the work of getting the access token with a mocked method * that will used mocked data instead of the output from the real `az` * command. - * @param resource The resources to use when accessing token + * @param resource - The resources to use when accessing token */ protected getAzureCliAccessToken( _resource: string diff --git a/sdk/identity/identity/tsdoc.json b/sdk/identity/identity/tsdoc.json new file mode 100644 index 000000000000..81c5a8a2aa2f --- /dev/null +++ b/sdk/identity/identity/tsdoc.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + "extends": ["../../../tsdoc.json"] +} diff --git a/sdk/keyvault/keyvault-admin/src/accessControlClient.ts b/sdk/keyvault/keyvault-admin/src/accessControlClient.ts index fb84c7dbfcfc..8da44f9df56b 100644 --- a/sdk/keyvault/keyvault-admin/src/accessControlClient.ts +++ b/sdk/keyvault/keyvault-admin/src/accessControlClient.ts @@ -52,7 +52,7 @@ export class KeyVaultAccessControlClient { /** * @internal - * @ignore + * @hidden * A reference to the auto-generated Key Vault HTTP client. */ private readonly client: KeyVaultClient; @@ -70,9 +70,9 @@ export class KeyVaultAccessControlClient { * * let client = new KeyVaultAccessControlClient(vaultUrl, credentials); * ``` - * @param vaultUrl the URL of the Key Vault. It should have this shape: https://${your-key-vault-name}.vault.azure.net - * @param credential An object that implements the `TokenCredential` interface used to authenticate requests to the service. Use the @azure/identity package to create a credential that suits your needs. - * @param [pipelineOptions] Pipeline options used to configure Key Vault API requests. Omit this parameter to use the default pipeline configuration. + * @param vaultUrl - the URL of the Key Vault. It should have this shape: `https://${your-key-vault-name}.vault.azure.net` + * @param credential - An object that implements the `TokenCredential` interface used to authenticate requests to the service. Use the \@azure/identity package to create a credential that suits your needs. + * @param pipelineOptions - Pipeline options used to configure Key Vault API requests. Omit this parameter to use the default pipeline configuration. */ constructor( vaultUrl: string, @@ -126,12 +126,12 @@ export class KeyVaultAccessControlClient { * const principalId = "4871f6a6-374f-4b6b-8b0c-f5d84db823f6"; * const result = await client.createRoleAssignment("/", "295c179b-9ad3-4117-99cd-b1aa66cf4517", roleDefinition, principalId); * ``` - * @summary Creates a new role assignment. - * @param roleScope The scope of the role assignment. - * @param name The name of the role assignment. Must be a UUID. - * @param roleDefinitionId The role definition ID used in the role assignment. - * @param principalId The principal ID assigned to the role. This maps to the ID inside the Active Directory. It can point to a user, service principal, or security group. - * @param [options] The optional parameters. + * Creates a new role assignment. + * @param roleScope - The scope of the role assignment. + * @param name - The name of the role assignment. Must be a UUID. + * @param roleDefinitionId - The role definition ID used in the role assignment. + * @param principalId - The principal ID assigned to the role. This maps to the ID inside the Active Directory. It can point to a user, service principal, or security group. + * @param options - The optional parameters. */ public async createRoleAssignment( roleScope: RoleAssignmentScope, @@ -179,10 +179,10 @@ export class KeyVaultAccessControlClient { * const deletedRoleAssignment = const await client.deleteRoleAssignment(roleAssignment.properties.roleScope, roleAssignment.name); * console.log(deletedRoleAssignment); * ``` - * @summary Deletes an existing role assignment. - * @param roleScope The scope of the role assignment. - * @param name The name of the role assignment. - * @param [options] The optional parameters. + * Deletes an existing role assignment. + * @param roleScope - The scope of the role assignment. + * @param name - The name of the role assignment. + * @param options - The optional parameters. */ public async deleteRoleAssignment( roleScope: RoleAssignmentScope, @@ -216,10 +216,10 @@ export class KeyVaultAccessControlClient { * roleAssignment = const await client.getRoleAssignment(roleAssignment.properties.roleScope, roleAssignment.name); * console.log(roleAssignment); * ``` - * @summary Gets an existing role assignment. - * @param roleScope The scope of the role assignment. - * @param name The name of the role assignment. - * @param [options] The optional parameters. + * Gets an existing role assignment. + * @param roleScope - The scope of the role assignment. + * @param name - The name of the role assignment. + * @param options - The optional parameters. */ public async getRoleAssignment( roleScope: RoleAssignmentScope, @@ -245,11 +245,11 @@ export class KeyVaultAccessControlClient { /** * @internal - * @ignore + * @hidden * Deals with the pagination of {@link listRoleAssignments}. - * @param roleScope The scope of the role assignments. - * @param continuationState An object that indicates the position of the paginated request. - * @param [options] Common options for the iterative endpoints. + * @param roleScope - The scope of the role assignments. + * @param continuationState - An object that indicates the position of the paginated request. + * @param options - Common options for the iterative endpoints. */ private async *listRoleAssignmentsPage( roleScope: RoleAssignmentScope, @@ -286,10 +286,10 @@ export class KeyVaultAccessControlClient { /** * @internal - * @ignore + * @hidden * Deals with the iteration of all the available results of {@link listRoleAssignments}. - * @param roleScope The scope of the role assignments. - * @param [options] Common options for the iterative endpoints. + * @param roleScope - The scope of the role assignments. + * @param options - Common options for the iterative endpoints. */ private async *listRoleAssignmentsAll( roleScope: RoleAssignmentScope, @@ -310,9 +310,9 @@ export class KeyVaultAccessControlClient { * console.log("Role assignment: ", roleAssignment); * } * ``` - * @summary Lists all of the role assignments in a given scope. - * @param roleScope The scope of the role assignments. - * @param [options] The optional parameters. + * Lists all of the role assignments in a given scope. + * @param roleScope - The scope of the role assignments. + * @param options - The optional parameters. */ public listRoleAssignments( roleScope: RoleAssignmentScope, @@ -341,11 +341,11 @@ export class KeyVaultAccessControlClient { /** * @internal - * @ignore + * @hidden * Deals with the pagination of {@link listRoleDefinitions}. - * @param roleScope The scope of the role definition. - * @param continuationState An object that indicates the position of the paginated request. - * @param [options] Common options for the iterative endpoints. + * @param roleScope - The scope of the role definition. + * @param continuationState - An object that indicates the position of the paginated request. + * @param options - Common options for the iterative endpoints. */ private async *listRoleDefinitionsPage( roleScope: RoleAssignmentScope, @@ -382,10 +382,10 @@ export class KeyVaultAccessControlClient { /** * @internal - * @ignore + * @hidden * Deals with the iteration of all the available results of {@link listRoleDefinitions}. - * @param roleScope The scope of the role definition. - * @param [options] Common options for the iterative endpoints. + * @param roleScope - The scope of the role definition. + * @param options - Common options for the iterative endpoints. */ private async *listRoleDefinitionsAll( roleScope: RoleAssignmentScope, @@ -406,9 +406,9 @@ export class KeyVaultAccessControlClient { * console.log("Role definition: ", roleDefinitions); * } * ``` - * @summary Lists all of the role definition in a given scope. - * @param roleScope The scope of the role definition. - * @param [options] The optional parameters. + * Lists all of the role definition in a given scope. + * @param roleScope - The scope of the role definition. + * @param options - The optional parameters. */ public listRoleDefinitions( roleScope: RoleAssignmentScope, diff --git a/sdk/keyvault/keyvault-admin/src/backupClient.ts b/sdk/keyvault/keyvault-admin/src/backupClient.ts index 03fb2c938c5b..50e3a926a2ab 100644 --- a/sdk/keyvault/keyvault-admin/src/backupClient.ts +++ b/sdk/keyvault/keyvault-admin/src/backupClient.ts @@ -45,7 +45,7 @@ export class KeyVaultBackupClient { /** * @internal - * @ignore + * @hidden * A reference to the auto-generated Key Vault HTTP client. */ private readonly client: KeyVaultClient; @@ -63,9 +63,9 @@ export class KeyVaultBackupClient { * * let client = new KeyVaultBackupClient(vaultUrl, credentials); * ``` - * @param vaultUrl the URL of the Key Vault. It should have this shape: https://${your-key-vault-name}.vault.azure.net - * @param credential An object that implements the `TokenCredential` interface used to authenticate requests to the service. Use the @azure/identity package to create a credential that suits your needs. - * @param [pipelineOptions] Pipeline options used to configure Key Vault API requests. Omit this parameter to use the default pipeline configuration. + * @param vaultUrl - the URL of the Key Vault. It should have this shape: `https://${your-key-vault-name}.vault.azure.net` + * @param credential - An object that implements the `TokenCredential` interface used to authenticate requests to the service. Use the \@azure/identity package to create a credential that suits your needs. + * @param pipelineOptions - Pipeline options used to configure Key Vault API requests. Omit this parameter to use the default pipeline configuration. */ constructor( vaultUrl: string, @@ -135,10 +135,10 @@ export class KeyVaultBackupClient { * const backupUri = await poller.pollUntilDone(); * console.log(backupUri); * ``` - * @summary Starts a full backup operation. - * @param blobStorageUri The URL of the blob storage resource, including the path to the container where the backup will end up being stored. - * @param sasToken The SAS token. - * @param [options] The optional parameters. + * Starts a full backup operation. + * @param blobStorageUri - The URL of the blob storage resource, including the path to the container where the backup will end up being stored. + * @param sasToken - The SAS token. + * @param options - The optional parameters. */ public async beginBackup( blobStorageUri: string, @@ -195,11 +195,11 @@ export class KeyVaultBackupClient { * const backupUri = await poller.pollUntilDone(); * console.log(backupUri); * ``` - * @summary Starts a full restore operation. - * @param blobStorageUri The URL of the blob storage resource where the previous successful full backup was stored. - * @param sasToken The SAS token. - * @param folderName The folder name of the blob where the previous successful full backup was stored. The URL segment after the container name. - * @param [options] The optional parameters. + * Starts a full restore operation. + * @param blobStorageUri - The URL of the blob storage resource where the previous successful full backup was stored. + * @param sasToken - The SAS token. + * @param folderName - The folder name of the blob where the previous successful full backup was stored. The URL segment after the container name. + * @param options - The optional parameters. */ public async beginRestore( blobStorageUri: string, @@ -258,12 +258,12 @@ export class KeyVaultBackupClient { * // Waiting until it's done * await poller.pollUntilDone(); * ``` - * @summary Creates a new role assignment. - * @param blobStorageUri The URL of the blob storage resource, with the folder name of the blob where the previous successful full backup was stored. - * @param sasToken The SAS token. - * @param folderName The Folder name of the blob where the previous successful full backup was stored. The URL segment after the container name. - * @param keyName The name of the key that wants to be restored. - * @param [options] The optional parameters. + * Creates a new role assignment. + * @param blobStorageUri - The URL of the blob storage resource, with the folder name of the blob where the previous successful full backup was stored. + * @param sasToken - The SAS token. + * @param folderName - The Folder name of the blob where the previous successful full backup was stored. The URL segment after the container name. + * @param keyName - The name of the key that wants to be restored. + * @param options - The optional parameters. */ public async beginSelectiveRestore( blobStorageUri: string, diff --git a/sdk/keyvault/keyvault-admin/src/log.ts b/sdk/keyvault/keyvault-admin/src/log.ts index 2aab0b1de238..d6bf7e958250 100644 --- a/sdk/keyvault/keyvault-admin/src/log.ts +++ b/sdk/keyvault/keyvault-admin/src/log.ts @@ -4,6 +4,6 @@ import { createClientLogger } from "@azure/logger"; /** - * The @azure/logger configuration for this package. + * The \@azure/logger configuration for this package. */ export const logger = createClientLogger("keyvault-admin"); diff --git a/sdk/keyvault/keyvault-admin/src/lro/keyVaultAdminPoller.ts b/sdk/keyvault/keyvault-admin/src/lro/keyVaultAdminPoller.ts index 34f52b69670a..3c0a3013e843 100644 --- a/sdk/keyvault/keyvault-admin/src/lro/keyVaultAdminPoller.ts +++ b/sdk/keyvault/keyvault-admin/src/lro/keyVaultAdminPoller.ts @@ -76,7 +76,6 @@ export abstract class KeyVaultAdminPoller< /** * The method used by the poller to wait before attempting to update its operation. - * @memberof DeleteKeyPoller */ async delay(): Promise { return delay(this.intervalInMs); diff --git a/sdk/keyvault/keyvault-admin/tsdoc.json b/sdk/keyvault/keyvault-admin/tsdoc.json new file mode 100644 index 000000000000..81c5a8a2aa2f --- /dev/null +++ b/sdk/keyvault/keyvault-admin/tsdoc.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + "extends": ["../../../tsdoc.json"] +} diff --git a/sdk/keyvault/keyvault-certificates/src/certificatesModels.ts b/sdk/keyvault/keyvault-certificates/src/certificatesModels.ts index 71c9ae936c16..859622781e39 100644 --- a/sdk/keyvault/keyvault-certificates/src/certificatesModels.ts +++ b/sdk/keyvault/keyvault-certificates/src/certificatesModels.ts @@ -8,7 +8,6 @@ import { DeletionRecoveryLevel, KeyUsageType } from "./generated/models"; * Defines values for CertificateKeyType. * Possible values include: 'EC', 'EC-HSM', 'RSA', 'RSA-HSM', 'oct' * @readonly - * @enum {string} */ export type CertificateKeyType = "EC" | "EC-HSM" | "RSA" | "RSA-HSM" | "oct"; @@ -16,7 +15,6 @@ export type CertificateKeyType = "EC" | "EC-HSM" | "RSA" | "RSA-HSM" | "oct"; * Defines values for CertificateKeyCurveName. * Possible values include: 'P-256', 'P-384', 'P-521', 'P-256K' * @readonly - * @enum {string} */ export type CertificateKeyCurveName = "P-256" | "P-384" | "P-521" | "P-256K"; @@ -119,7 +117,6 @@ export interface CertificateOperation { * Defines values for contentType. * Possible values include: 'application/x-pem-file', 'application/x-pkcs12' * @readonly - * @enum {string} */ export type CertificateContentType = "application/x-pem-file" | "application/x-pkcs12" | undefined; @@ -428,7 +425,7 @@ export interface CertificateProperties { readonly x509Thumbprint?: Uint8Array; /** * The retention dates of the softDelete data. - * The value should be >=7 and <=90 when softDelete enabled. + * The value should be `>=7` and `<=90` when softDelete enabled. * **NOTE: This property will not be serialized. It can only be populated by the server.** */ recoverableDays?: number; diff --git a/sdk/keyvault/keyvault-certificates/src/identifier.ts b/sdk/keyvault/keyvault-certificates/src/identifier.ts index ffded1718649..b6bff5f3345b 100644 --- a/sdk/keyvault/keyvault-certificates/src/identifier.ts +++ b/sdk/keyvault/keyvault-certificates/src/identifier.ts @@ -37,15 +37,15 @@ export interface KeyVaultCertificateId { * https://.vault.azure.net/certificates// * * On parsing the above Id, this function returns: - * + *```ts * { * sourceId: "https://.vault.azure.net/certificates//", * vaultUrl: "https://.vault.azure.net", * version: "", * name: "" * } - * - * @param id The Id of the Key Vault Certificate. + *``` + * @param id - The Id of the Key Vault Certificate. */ export function parseKeyVaultCertificateId(id: string): KeyVaultCertificateId { const urlParts = id.split("/"); diff --git a/sdk/keyvault/keyvault-certificates/src/index.ts b/sdk/keyvault/keyvault-certificates/src/index.ts index 66592fa1d855..5d49e9860835 100644 --- a/sdk/keyvault/keyvault-certificates/src/index.ts +++ b/sdk/keyvault/keyvault-certificates/src/index.ts @@ -256,11 +256,10 @@ export class CertificateClient { /** * Creates an instance of CertificateClient. - * @param {string} vaultUrl the base URL to the vault. - * @param {TokenCredential} credential An object that implements the `TokenCredential` interface used to authenticate requests to the service. Use the @azure/identity package to create a credential that suits your needs. - * @param {PipelineOptions} [pipelineOptions={}] Optional. Pipeline options used to configure Key Vault API requests. - * Omit this parameter to use the default pipeline configuration. - * @memberof CertificateClient + * @param vaultUrl - the base URL to the vault. + * @param credential - An object that implements the `TokenCredential` interface used to authenticate requests to the service. Use the \@azure/identity package to create a credential that suits your needs. + * @param pipelineOptions - Pipeline options used to configure Key Vault API requests. + * Omit this parameter to use the default pipeline configuration. */ constructor( vaultUrl: string, @@ -363,8 +362,8 @@ export class CertificateClient { * } * } * ``` - * @summary List all versions of the specified certificate. - * @param {ListPropertiesOfCertificatesOptions} [options] The optional parameters + * List all versions of the specified certificate. + * @param options - The optional parameters */ public listPropertiesOfCertificates( options: ListPropertiesOfCertificatesOptions = {} @@ -454,9 +453,9 @@ export class CertificateClient { * console.log(certificateProperties.version!); * } * ``` - * @summary List the versions of a certificate. - * @param certificateName The name of the certificate. - * @param {ListPropertiesOfCertificateVersionsOptions} [options] The optional parameters + * List the versions of a certificate. + * @param certificateName - The name of the certificate. + * @param options - The optional parameters */ public listPropertiesOfCertificateVersions( certificateName: string, @@ -511,9 +510,9 @@ export class CertificateClient { * const deletedCertificate = await deletePoller.pollUntilDone(); * console.log(deletedCertificate); * ``` - * @summary Deletes a certificate from a specified key vault. - * @param certificateName The name of the certificate. - * @param {DeleteCertificateOptions} [options] The optional parameters + * Deletes a certificate from a specified key vault. + * @param certificateName - The name of the certificate. + * @param options - The optional parameters */ public async beginDeleteCertificate( certificateName: string, @@ -545,8 +544,8 @@ export class CertificateClient { * }]); * await client.deleteContacts(); * ``` - * @summary Deletes all of the certificate contacts - * @param {DeleteContactsOptions} [options] The optional parameters + * Deletes all of the certificate contacts + * @param options - The optional parameters */ public async deleteContacts( options: DeleteContactsOptions = {} @@ -581,9 +580,9 @@ export class CertificateClient { * phone: "222222222222" * }]); * ``` - * @summary Sets the certificate contacts. - * @param contacts The contacts to use - * @param {SetContactsOptions} [options] The optional parameters + * Sets the certificate contacts. + * @param contacts - The contacts to use + * @param options - The optional parameters */ public async setContacts( contacts: CertificateContact[], @@ -626,8 +625,8 @@ export class CertificateClient { * const contacts = await client.getContacts(); * console.log(contacts); * ``` - * @summary Sets the certificate contacts. - * @param {GetContactsOptions} [options] The optional parameters + * Sets the certificate contacts. + * @param options - The optional parameters */ public async getContacts( options: GetContactsOptions = {} @@ -710,8 +709,8 @@ export class CertificateClient { * } * } * ``` - * @summary List the certificate issuers. - * @param {ListPropertiesOfIssuersOptions} [options] The optional parameters + * List the certificate issuers. + * @param options - The optional parameters */ public listPropertiesOfIssuers( options: ListPropertiesOfIssuersOptions = {} @@ -746,10 +745,10 @@ export class CertificateClient { * const client = new CertificateClient(url, credentials); * await client.createIssuer("IssuerName", "Test"); * ``` - * @summary Sets the specified certificate issuer. - * @param issuerName The name of the issuer. - * @param provider The issuer provider. - * @param {CreateIssuerOptions} [options] The optional parameters + * Sets the specified certificate issuer. + * @param issuerName - The name of the issuer. + * @param provider - The issuer provider. + * @param options - The optional parameters */ public async createIssuer( issuerName: string, @@ -828,9 +827,9 @@ export class CertificateClient { * provider: "Provider2" * }); * ``` - * @summary Updates the specified certificate issuer. - * @param issuerName The name of the issuer. - * @param {UpdateIssuerOptions} [options] The optional parameters + * Updates the specified certificate issuer. + * @param issuerName - The name of the issuer. + * @param options - The optional parameters */ public async updateIssuer( issuerName: string, @@ -902,9 +901,9 @@ export class CertificateClient { * const certificateIssuer = await client.getIssuer("IssuerName"); * console.log(certificateIssuer); * ``` - * @summary Gets he specified certificate issuer. - * @param issuerName The name of the issuer. - * @param {GetIssuerOptions} [options] The optional parameters + * Gets he specified certificate issuer. + * @param issuerName - The name of the issuer. + * @param options - The optional parameters */ public async getIssuer( issuerName: string, @@ -937,9 +936,9 @@ export class CertificateClient { * await client.createIssuer("IssuerName", "Provider"); * await client.deleteIssuer("IssuerName"); * ``` - * @summary Deletes the specified certificate issuer. - * @param issuerName The name of the issuer. - * @param {DeleteIssuerOptions} [options] The optional parameters + * Deletes the specified certificate issuer. + * @param issuerName - The name of the issuer. + * @param options - The optional parameters */ public async deleteIssuer( issuerName: string, @@ -993,10 +992,10 @@ export class CertificateClient { * const certificate = await createPoller.pollUntilDone(); * console.log(certificate); * ``` - * @summary Creates a certificate - * @param certificateName The name of the certificate - * @param certificatePolicy The certificate's policy - * @param {CreateCertificateOptions} [options] Optional parameters + * Creates a certificate + * @param certificateName - The name of the certificate + * @param certificatePolicy - The certificate's policy + * @param options - Optional parameters */ public async beginCreateCertificate( certificateName: string, @@ -1033,9 +1032,9 @@ export class CertificateClient { * const certificate = await client.getCertificate("MyCertificate"); * console.log(certificate); * ``` - * @summary Retrieves a certificate from the certificate's name (includes the certificate policy) - * @param certificateName The name of the certificate - * @param {GetCertificateOptions} [options] The optional parameters + * Retrieves a certificate from the certificate's name (includes the certificate policy) + * @param certificateName - The name of the certificate + * @param options - The optional parameters */ public async getCertificate( certificateName: string, @@ -1075,10 +1074,10 @@ export class CertificateClient { * const certificate = await client.getCertificateVersion("MyCertificate", certificateWithPolicy.properties.version!); * console.log(certificate); * ``` - * @summary Retrieves a certificate from the certificate's name and a specified version - * @param certificateName The name of the certificate - * @param version The specific version of the certificate - * @param options The optional parameters + * Retrieves a certificate from the certificate's name and a specified version + * @param certificateName - The name of the certificate + * @param version - The specific version of the certificate + * @param options - The optional parameters */ public async getCertificateVersion( certificateName: string, @@ -1128,10 +1127,10 @@ export class CertificateClient { * * await client.importCertificate("MyCertificate", buffer); * ``` - * @summary Imports a certificate from a certificate's secret value - * @param certificateName The name of the certificate - * @param certificateBytes The PFX or ASCII PEM formatted value of the certificate containing both the X.509 certificates and the private key - * @param {ImportCertificateOptions} [options] The optional parameters + * Imports a certificate from a certificate's secret value + * @param certificateName - The name of the certificate + * @param certificateBytes - The PFX or ASCII PEM formatted value of the certificate containing both the X.509 certificates and the private key + * @param options - The optional parameters */ public async importCertificate( certificateName: string, @@ -1176,9 +1175,9 @@ export class CertificateClient { * const policy = await client.getCertificatePolicy("MyCertificate"); * console.log(policy); * ``` - * @summary Gets a certificate's policy - * @param certificateName The name of the certificate - * @param {GetCertificatePolicyOptions} [options] The optional parameters + * Gets a certificate's policy + * @param certificateName - The name of the certificate + * @param options - The optional parameters */ public async getCertificatePolicy( certificateName: string, @@ -1204,10 +1203,10 @@ export class CertificateClient { /** * Updates the certificate policy for the specified certificate. This operation requires the certificates/update permission. - * @summary Gets a certificate's policy - * @param certificateName The name of the certificate - * @param policy The certificate policy - * @param {UpdateCertificatePolicyOptions} [options] The optional parameters + * Gets a certificate's policy + * @param certificateName - The name of the certificate + * @param policy - The certificate policy + * @param options - The optional parameters */ public async updateCertificatePolicy( certificateName: string, @@ -1250,10 +1249,10 @@ export class CertificateClient { * } * }); * ``` - * @summary Updates a certificate - * @param certificateName The name of the certificate - * @param version The version of the certificate to update - * @param options The options, including what to update + * Updates a certificate + * @param certificateName - The name of the certificate + * @param version - The version of the certificate to update + * @param options - The options, including what to update */ public async updateCertificateProperties( certificateName: string, @@ -1295,9 +1294,9 @@ export class CertificateClient { * const certificateOperation = poller.getOperationState().certificateOperation; * console.log(certificateOperation); * ``` - * @summary Gets a certificate's poller operation - * @param certificateName The name of the certificate - * @param {GetCertificateOperationOptions} [options] The optional parameters + * Gets a certificate's poller operation + * @param certificateName - The name of the certificate + * @param options - The optional parameters */ public async getCertificateOperation( certificateName: string, @@ -1331,9 +1330,9 @@ export class CertificateClient { * await client.deleteCertificateOperation("MyCertificate"); * await client.getCertificateOperation("MyCertificate"); // Throws error: Pending certificate not found: "MyCertificate" * ``` - * @summary Delete a certificate's operation - * @param certificateName The name of the certificate - * @param {DeleteCertificateOperationOptions} [options] The optional parameters + * Delete a certificate's operation + * @param certificateName - The name of the certificate + * @param options - The optional parameters */ public async deleteCertificateOperation( certificateName: string, @@ -1390,10 +1389,10 @@ export class CertificateClient { * * await client.mergeCertificate("MyCertificate", [Buffer.from(base64Crt)]); * ``` - * @summary Merges a signed certificate request into a pending certificate - * @param certificateName The name of the certificate - * @param x509Certificates The certificate(s) to merge - * @param {MergeCertificateOptions} [options] The optional parameters + * Merges a signed certificate request into a pending certificate + * @param certificateName - The name of the certificate + * @param x509Certificates - The certificate(s) to merge + * @param options - The optional parameters */ public async mergeCertificate( certificateName: string, @@ -1430,9 +1429,9 @@ export class CertificateClient { * }); * const backup = await client.backupCertificate("MyCertificate"); * ``` - * @summary Generates a backup of a certificate - * @param certificateName The name of the certificate - * @param {BackupCertificateOptions} [options] The optional parameters + * Generates a backup of a certificate + * @param certificateName - The name of the certificate + * @param options - The optional parameters */ public async backupCertificate( certificateName: string, @@ -1471,9 +1470,9 @@ export class CertificateClient { * // Some time is required before we're able to restore the certificate * await client.restoreCertificateBackup(backup!); * ``` - * @summary Restores a certificate from a backup - * @param backup The back-up certificate to restore from - * @param {RestoreCertificateBackupOptions} [options] The optional parameters + * Restores a certificate from a backup + * @param backup - The back-up certificate to restore from + * @param options - The optional parameters */ public async restoreCertificateBackup( backup: Uint8Array, @@ -1558,8 +1557,8 @@ export class CertificateClient { * } * } * ``` - * @summary Lists deleted certificates - * @param {ListDeletedCertificatesOptions} [options] The optional parameters + * Lists deleted certificates + * @param options - The optional parameters */ public listDeletedCertificates( options: ListDeletedCertificatesOptions = {} @@ -1595,9 +1594,9 @@ export class CertificateClient { * const deletedCertificate = await client.getDeletedCertificate("MyDeletedCertificate"); * console.log("Deleted certificate:", deletedCertificate); * ``` - * @summary Gets a deleted certificate - * @param certificateName The name of the certificate - * @param {GetDeletedCertificateOptions} [options] The optional parameters + * Gets a deleted certificate + * @param certificateName - The name of the certificate + * @param options - The optional parameters */ public async getDeletedCertificate( certificateName: string, @@ -1632,9 +1631,9 @@ export class CertificateClient { * // Deleting a certificate takes time, make sure to wait before purging it * client.purgeDeletedCertificate("MyCertificate"); * ``` - * @summary Gets a deleted certificate - * @param certificateName The name of the deleted certificate to purge - * @param {PurgeDeletedCertificateOptions} [options] The optional parameters + * Gets a deleted certificate + * @param certificateName - The name of the deleted certificate to purge + * @param options - The optional parameters */ public async purgeDeletedCertificate( certificateName: string, @@ -1681,9 +1680,9 @@ export class CertificateClient { * const certificate = await recoverPoller.pollUntilDone(); * console.log(certificate); * ``` - * @summary Recovers a deleted certificate - * @param certificateName The name of the deleted certificate - * @param {RecoverDeletedCertificateOptions} [options] The optional parameters + * Recovers a deleted certificate + * @param certificateName - The name of the deleted certificate + * @param options - The optional parameters */ public async beginRecoverDeletedCertificate( certificateName: string, diff --git a/sdk/keyvault/keyvault-certificates/src/log.ts b/sdk/keyvault/keyvault-certificates/src/log.ts index eea764021165..2a165697ba64 100644 --- a/sdk/keyvault/keyvault-certificates/src/log.ts +++ b/sdk/keyvault/keyvault-certificates/src/log.ts @@ -4,6 +4,6 @@ import { createClientLogger } from "@azure/logger"; /** - * The @azure/logger configuration for this package. + * The \@azure/logger configuration for this package. */ export const logger = createClientLogger("keyvault-certificates"); diff --git a/sdk/keyvault/keyvault-certificates/src/utils.ts b/sdk/keyvault/keyvault-certificates/src/utils.ts index bcbd64c3de1f..b0ab49569e6a 100644 --- a/sdk/keyvault/keyvault-certificates/src/utils.ts +++ b/sdk/keyvault/keyvault-certificates/src/utils.ts @@ -7,7 +7,7 @@ import { CertificateContentType } from "./certificatesModels"; /** * Decodes a Uint8Array into a Base64 string. * @internal - * @param bytes Uint8Array + * @param bytes - */ export function toBase64(bytes: Uint8Array): string { if (isNode) { @@ -20,7 +20,7 @@ export function toBase64(bytes: Uint8Array): string { /** * Decodes a Uint8Array into an ASCII string. * @internal - * @param bytes Uint8Array + * @param bytes - */ export function toAscii(bytes: Uint8Array): string { if (isNode) { @@ -33,7 +33,7 @@ export function toAscii(bytes: Uint8Array): string { /** * Encodes a JavaScript string into a Uint8Array. * @internal - * @param value string + * @param value - */ export function stringToUint8Array(value: string): Uint8Array { if (isNode) { @@ -46,7 +46,7 @@ export function stringToUint8Array(value: string): Uint8Array { /** * Encodes a Base64 string into a Uint8Array. * @internal - * @param value string + * @param value - */ export function base64ToUint8Array(value: string): Uint8Array { if (isNode) { @@ -61,8 +61,8 @@ export function base64ToUint8Array(value: string): Uint8Array { * into a Base64 encoded string. * * @internal - * @param certificateBytes The PFX or ASCII PEM formatted value of the certificate containing both the X.509 certificates and the private key - * @param contentType "application/x-pem-file", "application/x-pkcs12" or undefined + * @param certificateBytes - The PFX or ASCII PEM formatted value of the certificate containing both the X.509 certificates and the private key + * @param contentType - "application/x-pem-file", "application/x-pkcs12" or undefined */ export function parseCertificateBytes( certificateBytes: Uint8Array, diff --git a/sdk/keyvault/keyvault-certificates/test/utils/lro/restore/operation.ts b/sdk/keyvault/keyvault-certificates/test/utils/lro/restore/operation.ts index ee5fdd2d85e3..db81fccc0c19 100644 --- a/sdk/keyvault/keyvault-certificates/test/utils/lro/restore/operation.ts +++ b/sdk/keyvault/keyvault-certificates/test/utils/lro/restore/operation.ts @@ -13,7 +13,7 @@ export interface BeginRestoreCertificateBackupOptions extends CertificatePollerO /** * @internal - * @ignore + * @hidden * An interface representing the CertificateClient. For internal use. */ export interface TestCertificateClientInterface { @@ -53,8 +53,8 @@ export interface RestoreCertificateBackupPollOperation extends PollOperation {} /** - * @summary Reaches to the service and updates the restore certificate's poll operation. - * @param [options] The optional parameters, which are an abortSignal from @azure/abort-controller and a function that triggers the poller's onProgress function. + * Reaches to the service and updates the restore certificate's poll operation. + * @param options - The optional parameters, which are an abortSignal from \@azure/abort-controller and a function that triggers the poller's onProgress function. */ async function update( this: RestoreCertificateBackupPollOperation, @@ -85,14 +85,14 @@ async function update( } /** - * @param [options] The optional parameters, which is only an abortSignal from @azure/abort-controller + * @param options - The optional parameters, which is only an abortSignal from \@azure/abort-controller */ async function cancel(this: RestoreCertificateBackupPollOperation): Promise { throw new Error("Canceling the restoration of a certificate is not supported."); } /** - * @summary Serializes the create certificate's poll operation + * Serializes the create certificate's poll operation */ function toString(this: RestoreCertificateBackupPollOperation): string { return JSON.stringify({ @@ -101,8 +101,8 @@ function toString(this: RestoreCertificateBackupPollOperation): string { } /** - * @summary Builds a create certificate's poll operation - * @param [state] A poll operation's state, in case the new one is intended to follow up where the previous one was left. + * Builds a create certificate's poll operation + * @param state - A poll operation's state, in case the new one is intended to follow up where the previous one was left. */ export function makeRestoreCertificateBackupPollOperation( state: RestoreCertificateBackupPollOperationState diff --git a/sdk/keyvault/keyvault-certificates/test/utils/lro/restore/poller.ts b/sdk/keyvault/keyvault-certificates/test/utils/lro/restore/poller.ts index c5fab3a57f72..70ea5ec4683c 100644 --- a/sdk/keyvault/keyvault-certificates/test/utils/lro/restore/poller.ts +++ b/sdk/keyvault/keyvault-certificates/test/utils/lro/restore/poller.ts @@ -27,7 +27,6 @@ export class RestoreCertificateBackupPoller extends Poller< > { /** * Defines how much time the poller is going to wait before making a new request to the service. - * @memberof RestoreCertificateBackupPoller */ public intervalInMs: number; @@ -54,7 +53,6 @@ export class RestoreCertificateBackupPoller extends Poller< /** * The method used by the poller to wait before attempting to update its operation. - * @memberof RestoreCertificateBackupPoller */ async delay(): Promise { return delay(this.intervalInMs); diff --git a/sdk/keyvault/keyvault-certificates/tsdoc.json b/sdk/keyvault/keyvault-certificates/tsdoc.json new file mode 100644 index 000000000000..81c5a8a2aa2f --- /dev/null +++ b/sdk/keyvault/keyvault-certificates/tsdoc.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + "extends": ["../../../tsdoc.json"] +} diff --git a/sdk/keyvault/keyvault-common/src/challengeBasedAuthenticationPolicy.ts b/sdk/keyvault/keyvault-common/src/challengeBasedAuthenticationPolicy.ts index 5ffee8db333e..86672ba3b91d 100644 --- a/sdk/keyvault/keyvault-common/src/challengeBasedAuthenticationPolicy.ts +++ b/sdk/keyvault/keyvault-common/src/challengeBasedAuthenticationPolicy.ts @@ -38,7 +38,7 @@ export class AuthenticationChallenge { * Only compares the scope. * This is exactly what C# is doing, as we can see here: * https://github.com/Azure/azure-sdk-for-net/blob/70e54b878ff1d01a45266fb3674a396b4ab9c1d2/sdk/keyvault/Azure.Security.KeyVault.Shared/src/ChallengeBasedAuthenticationPolicy.cs#L143-L147 - * @param other The other AuthenticationChallenge + * @param other - The other AuthenticationChallenge */ public equalTo(other: AuthenticationChallenge | undefined): boolean { return other @@ -63,7 +63,7 @@ export class AuthenticationChallengeCache { /** * Creates a new ChallengeBasedAuthenticationPolicy factory. * - * @param credential The TokenCredential implementation that can supply the challenge token. + * @param credential - The TokenCredential implementation that can supply the challenge token. */ export function challengeBasedAuthenticationPolicy( credential: TokenCredential @@ -89,7 +89,7 @@ export function challengeBasedAuthenticationPolicy( * `Bearer authorization="some_authorization", resource="https://some.url"` * into an object like: * `{ authorization: "some_authorization", resource: "https://some.url" }` - * @param wwwAuthenticate string value in the WWW-Authenticate header + * @param wwwAuthenticate - String value in the WWW-Authenticate header */ export function parseWWWAuthenticate(wwwAuthenticate: string): ParsedWWWAuthenticate { // First we split the string by either `, ` or ` `. @@ -126,10 +126,10 @@ export class ChallengeBasedAuthenticationPolicy extends BaseRequestPolicy { /** * Creates a new ChallengeBasedAuthenticationPolicy object. * - * @param nextPolicy The next RequestPolicy in the request pipeline. - * @param options Options for this RequestPolicy. - * @param credential The TokenCredential implementation that can supply the bearer token. - * @param tokenCache The cache for the most recent AccessToken returned by the TokenCredential. + * @param nextPolicy - The next RequestPolicy in the request pipeline. + * @param options - Options for this RequestPolicy. + * @param credential - The TokenCredential implementation that can supply the bearer token. + * @param tokenCache - The cache for the most recent AccessToken returned by the TokenCredential. */ constructor( nextPolicy: RequestPolicy, @@ -166,8 +166,8 @@ export class ChallengeBasedAuthenticationPolicy extends BaseRequestPolicy { * Parses the given WWW-Authenticate header, generates a new AuthenticationChallenge, * then if the challenge is different from the one cached, resets the token and forces * a re-authentication, otherwise continues with the existing challenge and token. - * @param wwwAuthenticate Value of the incoming WWW-Authenticate header. - * @param webResource Ongoing HTTP request. + * @param wwwAuthenticate - Value of the incoming WWW-Authenticate header. + * @param webResource - Ongoing HTTP request. */ private async regenerateChallenge( wwwAuthenticate: string, @@ -200,7 +200,7 @@ export class ChallengeBasedAuthenticationPolicy extends BaseRequestPolicy { /** * Applies the Bearer token to the request through the Authorization header. - * @param webResource Ongoing HTTP request. + * @param webResource - Ongoing HTTP request. */ public async sendRequest(webResource: WebResource): Promise { // Ensure that we're about to use a secure connection. diff --git a/sdk/keyvault/keyvault-common/src/tracing.ts b/sdk/keyvault/keyvault-common/src/tracing.ts index a97d4bd52abd..147495f5f396 100644 --- a/sdk/keyvault/keyvault-common/src/tracing.ts +++ b/sdk/keyvault/keyvault-common/src/tracing.ts @@ -7,8 +7,8 @@ import { Span } from "@opentelemetry/api"; /** * Creates a span using the tracer that was set by the user - * @param {string} methodName The name of the method creating the span. - * @param {RequestOptionsBase} [options] The options for the underlying HTTP request. + * @param methodName - The name of the method creating the span. + * @param options - The options for the underlying HTTP request. */ export function createSpan(methodName: string, requestOptions: RequestOptionsBase = {}): Span { const tracer = getTracer(); @@ -20,8 +20,8 @@ export function createSpan(methodName: string, requestOptions: RequestOptionsBas /** * Returns updated HTTP options with the given span as the parent of future spans, * if applicable. - * @param {Span} span The span for the current operation. - * @param {RequestOptionsBase} [options] The options for the underlying HTTP request. + * @param span - The span for the current operation. + * @param options - The options for the underlying HTTP request. */ export function setParentSpan(span: Span, options: RequestOptionsBase = {}): RequestOptionsBase { if (span.isRecording()) { diff --git a/sdk/keyvault/keyvault-keys/src/cryptographyClient.ts b/sdk/keyvault/keyvault-keys/src/cryptographyClient.ts index 622b3430c89e..e968fcf21c65 100644 --- a/sdk/keyvault/keyvault-keys/src/cryptographyClient.ts +++ b/sdk/keyvault/keyvault-keys/src/cryptographyClient.ts @@ -85,7 +85,7 @@ export function checkKeyValidity(keyId?: string, keyBundle?: KeyBundle): void { export class CryptographyClient { /** * @internal - * @ignore + * @hidden * Retrieves the {@link JsonWebKey} from the Key Vault. * * Example usage: @@ -93,7 +93,7 @@ export class CryptographyClient { * let client = new CryptographyClient(keyVaultKey, credentials); * let result = await client.getKey(); * ``` - * @param {GetKeyOptions} [options] Options for retrieving key. + * @param options - Options for retrieving key. */ private async getKey(options: GetKeyOptions = {}): Promise { const requestOptions = operationOptionsToRequestOptionsBase(options); @@ -124,9 +124,9 @@ export class CryptographyClient { * let client = new CryptographyClient(keyVaultKey, credentials); * let result = await client.encrypt("RSA1_5", Buffer.from("My Message")); * ``` - * @param {EncryptionAlgorithm} algorithm The algorithm to use. - * @param {Uint8Array} plaintext The text to encrypt. - * @param {EncryptOptions} [options] Additional options. + * @param algorithm - The algorithm to use. + * @param plaintext - The text to encrypt. + * @param options - Additional options. */ public async encrypt( algorithm: EncryptionAlgorithm, @@ -179,9 +179,9 @@ export class CryptographyClient { * let client = new CryptographyClient(keyVaultKey, credentials); * let result = await client.decrypt("RSA1_5", encryptedBuffer); * ``` - * @param {EncryptionAlgorithm} algorithm The algorithm to use. - * @param {Uint8Array} ciphertext The text to decrypt. - * @param {DecryptOptions} [options] Additional options. + * @param algorithm - The algorithm to use. + * @param ciphertext - The text to decrypt. + * @param options - Additional options. */ public async decrypt( @@ -223,9 +223,9 @@ export class CryptographyClient { * let client = new CryptographyClient(keyVaultKey, credentials); * let result = await client.wrapKey("RSA1_5", keyToWrap); * ``` - * @param {KeyWrapAlgorithm} algorithm The encryption algorithm to use to wrap the given key. - * @param {Uint8Array} key The key to wrap. - * @param {WrapKeyOptions} [options] Additional options. + * @param algorithm - The encryption algorithm to use to wrap the given key. + * @param key - The key to wrap. + * @param options - Additional options. */ public async wrapKey( algorithm: KeyWrapAlgorithm, @@ -278,9 +278,9 @@ export class CryptographyClient { * let client = new CryptographyClient(keyVaultKey, credentials); * let result = await client.unwrapKey("RSA1_5", keyToUnwrap); * ``` - * @param {KeyWrapAlgorithm} algorithm The decryption algorithm to use to unwrap the key. - * @param {Uint8Array} encryptedKey The encrypted key to unwrap. - * @param {UnwrapKeyOptions} [options] Additional options. + * @param algorithm - The decryption algorithm to use to unwrap the key. + * @param encryptedKey - The encrypted key to unwrap. + * @param options - Additional options. */ public async unwrapKey( algorithm: KeyWrapAlgorithm, @@ -321,9 +321,9 @@ export class CryptographyClient { * let client = new CryptographyClient(keyVaultKey, credentials); * let result = await client.sign("RS256", digest); * ``` - * @param {KeySignatureAlgorithm} algorithm The signing algorithm to use. - * @param {Uint8Array} digest The digest of the data to sign. - * @param {SignOptions} [options] Additional options. + * @param algorithm - The signing algorithm to use. + * @param digest - The digest of the data to sign. + * @param options - Additional options. */ public async sign( algorithm: SignatureAlgorithm, @@ -362,10 +362,10 @@ export class CryptographyClient { * let client = new CryptographyClient(keyVaultKey, credentials); * let result = await client.verify("RS256", signedDigest, signature); * ``` - * @param {KeySignatureAlgorithm} algorithm The signing algorithm to use to verify with. - * @param {Uint8Array} digest The digest to verify. - * @param {Uint8Array} signature The signature to verify the digest against. - * @param {VerifyOptions} [options] Additional options. + * @param algorithm - The signing algorithm to use to verify with. + * @param digest - The digest to verify. + * @param signature - The signature to verify the digest against. + * @param options - Additional options. */ public async verify( algorithm: SignatureAlgorithm, @@ -406,9 +406,9 @@ export class CryptographyClient { * let client = new CryptographyClient(keyVaultKey, credentials); * let result = await client.signData("RS256", message); * ``` - * @param {KeySignatureAlgorithm} algorithm The signing algorithm to use. - * @param {Uint8Array} data The data to sign. - * @param {SignOptions} [options] Additional options. + * @param algorithm - The signing algorithm to use. + * @param data - The data to sign. + * @param options - Additional options. */ public async signData( algorithm: SignatureAlgorithm, @@ -460,10 +460,10 @@ export class CryptographyClient { * let client = new CryptographyClient(keyVaultKey, credentials); * let result = await client.verifyData("RS256", signedMessage, signature); * ``` - * @param {KeySignatureAlgorithm} algorithm The algorithm to use to verify with. - * @param {Uint8Array} data The signed block of data to verify. - * @param {Uint8Array} signature The signature to verify the block against. - * @param {VerifyOptions} [options] Additional options. + * @param algorithm - The algorithm to use to verify with. + * @param data - The signed block of data to verify. + * @param signature - The signature to verify the block against. + * @param options - Additional options. */ public async verifyData( algorithm: SignatureAlgorithm, @@ -521,7 +521,7 @@ export class CryptographyClient { /** * @internal - * @ignore + * @hidden * Attempts to retrieve the ID of the key. */ private getKeyID(): string | undefined { @@ -542,7 +542,7 @@ export class CryptographyClient { /** * @internal - * @ignore + * @hidden * A reference to the auto-generated KeyVault HTTP client. */ private readonly client: KeyVaultClient; @@ -606,11 +606,10 @@ export class CryptographyClient { * // or * let client = new CryptographyClient(keyVaultKey, credentials); * ``` - * @param key The key to use during cryptography tasks. You can also pass the identifier of the key i.e its url here. - * @param {TokenCredential} credential An object that implements the `TokenCredential` interface used to authenticate requests to the service. Use the @azure/identity package to create a credential that suits your needs. - * @param {PipelineOptions} [pipelineOptions={}] Optional. Pipeline options used to configure Key Vault API requests. - * Omit this parameter to use the default pipeline configuration. - * @memberof CryptographyClient + * @param key - The key to use during cryptography tasks. You can also pass the identifier of the key i.e its url here. + * @param credential - An object that implements the `TokenCredential` interface used to authenticate requests to the service. Use the \@azure/identity package to create a credential that suits your needs. + * @param pipelineOptions - Pipeline options used to configure Key Vault API requests. + * Omit this parameter to use the default pipeline configuration. */ constructor( key: string | KeyVaultKey, @@ -681,10 +680,10 @@ export class CryptographyClient { /** * @internal - * @ignore + * @hidden * Creates a span using the tracer that was set by the user. - * @param {string} methodName The name of the method creating the span. - * @param {RequestOptionsBase} [options] The options for the underlying HTTP request. + * @param methodName - The name of the method creating the span. + * @param options - The options for the underlying HTTP request. */ private createSpan(methodName: string, requestOptions?: RequestOptionsBase): Span { const tracer = getTracer(); @@ -698,7 +697,7 @@ export class CryptographyClient { /** * Checks whether the internal key can be used to execute a given operation, by the operation's name. - * @param operation The name of the operation that is expected to be viable + * @param operation - The name of the operation that is expected to be viable */ private async checkPermissions(operation: KeyOperation): Promise { await this.getLocalCryptographyClient(); diff --git a/sdk/keyvault/keyvault-keys/src/cryptographyClientModels.ts b/sdk/keyvault/keyvault-keys/src/cryptographyClientModels.ts index e5764a864657..cfd9e513ad9f 100644 --- a/sdk/keyvault/keyvault-keys/src/cryptographyClientModels.ts +++ b/sdk/keyvault/keyvault-keys/src/cryptographyClientModels.ts @@ -6,7 +6,6 @@ import { CryptographyOptions } from "./keysModels"; /** * Defines values for SignatureAlgorithm. * @readonly - * @enum {string} */ export type SignatureAlgorithm = | "PS256" @@ -24,7 +23,6 @@ export type SignatureAlgorithm = * Defines values for EncryptionAlgorithm. * Possible values include: 'RSA-OAEP', 'RSA-OAEP-256', 'RSA1_5', 'A128GCM', 'A192GCM', 'A256GCM', 'A128KW', 'A192KW', 'A256KW', 'A128CBC', 'A192CBC', 'A256CBC', 'A128CBCPAD', 'A192CBCPAD', 'A256CBCPAD' * @readonly - * @enum {string} */ export type EncryptionAlgorithm = | "RSA-OAEP" @@ -47,7 +45,6 @@ export type EncryptionAlgorithm = * Defines values for KeyCurveName. * Possible values include: 'P-256', 'P-384', 'P-521', 'P-256K' * @readonly - * @enum {string} */ export type KeyCurveName = "P-256" | "P-384" | "P-521" | "P-256K"; diff --git a/sdk/keyvault/keyvault-keys/src/identifier.ts b/sdk/keyvault/keyvault-keys/src/identifier.ts index b700badd76ab..59374e4f9820 100644 --- a/sdk/keyvault/keyvault-keys/src/identifier.ts +++ b/sdk/keyvault/keyvault-keys/src/identifier.ts @@ -37,15 +37,16 @@ export interface KeyVaultKeyId { * https://.vault.azure.net/keys// * * On parsing the above Id, this function returns: - * + *```ts * { * sourceId: "https://.vault.azure.net/keys//", * vaultUrl: "https://.vault.azure.net", * version: "", * name: "" * } - * - * @param id The Id of the Key Vault Key. + *``` + + * @param id - The Id of the Key Vault Key. */ export function parseKeyVaultKeyId(id: string): KeyVaultKeyId { const urlParts = id.split("/"); diff --git a/sdk/keyvault/keyvault-keys/src/index.ts b/sdk/keyvault/keyvault-keys/src/index.ts index e75e8b7a3ef5..ce92342fe8ec 100644 --- a/sdk/keyvault/keyvault-keys/src/index.ts +++ b/sdk/keyvault/keyvault-keys/src/index.ts @@ -170,7 +170,7 @@ export class KeyClient { /** * @internal - * @ignore + * @hidden * A reference to the auto-generated Key Vault HTTP client. */ private readonly client: KeyVaultClient; @@ -188,10 +188,9 @@ export class KeyClient { * * let client = new KeyClient(vaultUrl, credentials); * ``` - * @param {string} vaultUrl the URL of the Key Vault. It should have this shape: https://${your-key-vault-name}.vault.azure.net - * @param {TokenCredential} credential An object that implements the `TokenCredential` interface used to authenticate requests to the service. Use the @azure/identity package to create a credential that suits your needs. - * @param {PipelineOptions} [pipelineOptions] Pipeline options used to configure Key Vault API requests. Omit this parameter to use the default pipeline configuration. - * @memberof KeyClient + * @param vaultUrl - the URL of the Key Vault. It should have this shape: `https://${your-key-vault-name}.vault.azure.net` + * @param credential - An object that implements the `TokenCredential` interface used to authenticate requests to the service. Use the \@azure/identity package to create a credential that suits your needs. + * @param pipelineOptions - Pipeline options used to configure Key Vault API requests. Omit this parameter to use the default pipeline configuration. */ constructor( vaultUrl: string, @@ -244,10 +243,10 @@ export class KeyClient { * // Create an elliptic-curve key: * let result = await client.createKey("MyKey", "EC"); * ``` - * @summary Creates a new key, stores it, then returns key parameters and properties to the client. - * @param {string} name The name of the key. - * @param {KeyType} keyType The type of the key. One of the following: 'EC', 'EC-HSM', 'RSA', 'RSA-HSM', 'oct'. - * @param {CreateKeyOptions} [options] The optional parameters. + * Creates a new key, stores it, then returns key parameters and properties to the client. + * @param name - The name of the key. + * @param keyType - The type of the key. One of the following: 'EC', 'EC-HSM', 'RSA', 'RSA-HSM', 'oct'. + * @param options - The optional parameters. */ public async createKey( name: string, @@ -297,9 +296,9 @@ export class KeyClient { * let client = new KeyClient(url, credentials); * let result = await client.createEcKey("MyKey", { curve: "P-256" }); * ``` - * @summary Creates a new key, stores it, then returns key parameters and properties to the client. - * @param {string} name The name of the key. - * @param {CreateEcKeyOptions} [options] The optional parameters. + * Creates a new key, stores it, then returns key parameters and properties to the client. + * @param name - The name of the key. + * @param options - The optional parameters. */ public async createEcKey(name: string, options?: CreateEcKeyOptions): Promise { if (options) { @@ -345,9 +344,9 @@ export class KeyClient { * let client = new KeyClient(url, credentials); * let result = await client.createRsaKey("MyKey", { keySize: 2048 }); * ``` - * @summary Creates a new key, stores it, then returns key parameters and properties to the client. - * @param {string} name The name of the key. - * @param {CreateRsaKeyOptions} [options] The optional parameters. + * Creates a new key, stores it, then returns key parameters and properties to the client. + * @param name - The name of the key. + * @param options - The optional parameters. */ public async createRsaKey(name: string, options?: CreateRsaKeyOptions): Promise { if (options) { @@ -394,11 +393,11 @@ export class KeyClient { * // Key contents in myKeyContents * let result = await client.importKey("MyKey", myKeyContents); * ``` - * @summary Imports an externally created key, stores it, and returns key parameters and properties + * Imports an externally created key, stores it, and returns key parameters and properties * to the client. - * @param {string} name Name for the imported key. - * @param {JsonWebKey} key The JSON web key. - * @param {ImportKeyOptions} [options] The optional parameters. + * @param name - Name for the imported key. + * @param key - The JSON web key. + * @param options - The optional parameters. */ public async importKey( name: string, @@ -468,9 +467,9 @@ export class KeyClient { * const deletedKey = await poller.pollUntilDone(); * console.log(deletedKey); * ``` - * @summary Deletes a key from a specified key vault. - * @param {string} name The name of the key. - * @param {BeginDeleteKeyOptions} [options] The optional parameters. + * Deletes a key from a specified key vault. + * @param name - The name of the key. + * @param options - The optional parameters. */ public async beginDeleteKey( name: string, @@ -504,10 +503,10 @@ export class KeyClient { * let key = await client.getKey(keyName); * let result = await client.updateKeyProperties(keyName, key.properties.version, { enabled: false }); * ``` - * @summary Updates the properties associated with a specified key in a given key vault. - * @param {string} name The name of the key. - * @param {string} keyVersion The version of the key. - * @param {UpdateKeyPropertiesOptions} [options] The optional parameters. + * Updates the properties associated with a specified key in a given key vault. + * @param name - The name of the key. + * @param keyVersion - The version of the key. + * @param options - The optional parameters. */ public async updateKeyProperties( name: string, @@ -557,9 +556,9 @@ export class KeyClient { * let client = new KeyClient(url, credentials); * let key = await client.getKey("MyKey"); * ``` - * @summary Get a specified key from a given key vault. - * @param {string} name The name of the key. - * @param {GetKeyOptions} [options] The optional parameters. + * Get a specified key from a given key vault. + * @param name - The name of the key. + * @param options - The optional parameters. */ public async getKey(name: string, options: GetKeyOptions = {}): Promise { const requestOptions = operationOptionsToRequestOptionsBase(options); @@ -589,9 +588,9 @@ export class KeyClient { * let client = new KeyClient(url, credentials); * let key = await client.getDeletedKey("MyDeletedKey"); * ``` - * @summary Gets the specified deleted key. - * @param {string} name The name of the key. - * @param {GetDeletedKeyOptions} [options] The optional parameters. + * Gets the specified deleted key. + * @param name - The name of the key. + * @param options - The optional parameters. */ public async getDeletedKey( name: string, @@ -626,9 +625,9 @@ export class KeyClient { * await deletePoller.pollUntilDone(); * await client.purgeDeletedKey("MyKey"); * ``` - * @summary Permanently deletes the specified key. - * @param name The name of the key. - * @param {PurgeDeletedKeyOptions} [options] The optional parameters. + * Permanently deletes the specified key. + * @param name - The name of the key. + * @param options - The optional parameters. */ public async purgeDeletedKey(name: string, options: PurgeDeletedKeyOptions = {}): Promise { const responseOptions = operationOptionsToRequestOptionsBase(options); @@ -666,9 +665,9 @@ export class KeyClient { * const key = await poller.pollUntilDone(); * console.log(key); * ``` - * @summary Recovers the deleted key to the latest version. - * @param name The name of the deleted key. - * @param {BeginRecoverDeletedKeyOptions} [options] The optional parameters. + * Recovers the deleted key to the latest version. + * @param name - The name of the deleted key. + * @param options - The optional parameters. */ public async beginRecoverDeletedKey( name: string, @@ -698,9 +697,9 @@ export class KeyClient { * let client = new KeyClient(url, credentials); * let backupContents = await client.backupKey("MyKey"); * ``` - * @summary Backs up the specified key. - * @param {string} name The name of the key. - * @param {BackupKeyOptions} [options] The optional parameters. + * Backs up the specified key. + * @param name - The name of the key. + * @param options - The optional parameters. */ public async backupKey( name: string, @@ -734,9 +733,9 @@ export class KeyClient { * // ... * let key = await client.restoreKeyBackup(backupContents); * ``` - * @summary Restores a backed up key to a vault. - * @param {Uint8Array} backup The backup blob associated with a key bundle. - * @param {RestoreKeyBackupOptions} [options] The optional parameters. + * Restores a backed up key to a vault. + * @param backup - The backup blob associated with a key bundle. + * @param options - The optional parameters. */ public async restoreKeyBackup( backup: Uint8Array, @@ -761,11 +760,11 @@ export class KeyClient { /** * @internal - * @ignore + * @hidden * Deals with the pagination of {@link listPropertiesOfKeyVersions}. - * @param {string} name The name of the Key Vault Key. - * @param {PageSettings} continuationState An object that indicates the position of the paginated request. - * @param {ListPropertiesOfKeyVersionsOptions} [options] Common options for the iterative endpoints. + * @param name - The name of the Key Vault Key. + * @param continuationState - An object that indicates the position of the paginated request. + * @param options - Common options for the iterative endpoints. */ private async *listPropertiesOfKeyVersionsPage( name: string, @@ -804,10 +803,10 @@ export class KeyClient { /** * @internal - * @ignore + * @hidden * Deals with the iteration of all the available results of {@link listPropertiesOfKeyVersions}. - * @param {string} name The name of the Key Vault Key. - * @param {ListPropertiesOfKeyVersionsOptions} [options] Common options for the iterative endpoints. + * @param name - The name of the Key Vault Key. + * @param options - Common options for the iterative endpoints. */ private async *listPropertiesOfKeyVersionsAll( name: string, @@ -834,8 +833,8 @@ export class KeyClient { * console.log("key version: ", key); * } * ``` - * @param {string} name Name of the key to fetch versions for - * @param {ListPropertiesOfKeyVersionsOptions} [options] The optional parameters. + * @param name - Name of the key to fetch versions for + * @param options - The optional parameters. */ public listPropertiesOfKeyVersions( name: string, @@ -865,10 +864,10 @@ export class KeyClient { /** * @internal - * @ignore + * @hidden * Deals with the pagination of {@link listPropertiesOfKeys}. - * @param {PageSettings} continuationState An object that indicates the position of the paginated request. - * @param {ListPropertiesOfKeysOptions} [options] Common options for the iterative endpoints. + * @param continuationState - An object that indicates the position of the paginated request. + * @param options - Common options for the iterative endpoints. */ private async *listPropertiesOfKeysPage( continuationState: PageSettings, @@ -901,9 +900,9 @@ export class KeyClient { /** * @internal - * @ignore + * @hidden * Deals with the iteration of all the available results of {@link listPropertiesOfKeys}. - * @param {ListPropertiesOfKeysOptions} [options] Common options for the iterative endpoints. + * @param options - Common options for the iterative endpoints. */ private async *listPropertiesOfKeysAll( options?: ListPropertiesOfKeysOptions @@ -929,8 +928,8 @@ export class KeyClient { * console.log("key: ", key); * } * ``` - * @summary List all keys in the vault - * @param {ListPropertiesOfKeysOptions} [options] The optional parameters. + * List all keys in the vault + * @param options - The optional parameters. */ public listPropertiesOfKeys( options: ListPropertiesOfKeysOptions = {} @@ -959,10 +958,10 @@ export class KeyClient { /** * @internal - * @ignore + * @hidden * Deals with the pagination of {@link listDeletedKeys}. - * @param {PageSettings} continuationState An object that indicates the position of the paginated request. - * @param {ListDeletedKeysOptions} [options] Common options for the iterative endpoints. + * @param continuationState - An object that indicates the position of the paginated request. + * @param options - Common options for the iterative endpoints. */ private async *listDeletedKeysPage( continuationState: PageSettings, @@ -995,9 +994,9 @@ export class KeyClient { /** * @internal - * @ignore + * @hidden * Deals with the iteration of all the available results of {@link listDeletedKeys}. - * @param {ListDeletedKeysOptions} [options] Common options for the iterative endpoints. + * @param options - Common options for the iterative endpoints. */ private async *listDeletedKeysAll( options?: ListDeletedKeysOptions @@ -1022,8 +1021,8 @@ export class KeyClient { * console.log("deleted key: ", deletedKey); * } * ``` - * @summary List all keys in the vault - * @param {ListDeletedKeysOptions} [options] The optional parameters. + * List all keys in the vault + * @param options - The optional parameters. */ public listDeletedKeys( options: ListDeletedKeysOptions = {} @@ -1052,7 +1051,7 @@ export class KeyClient { /** * @internal - * @ignore + * @hidden * Shapes the exposed {@link DeletedKey} based on a received KeyItem. */ private getDeletedKeyFromKeyItem(keyItem: KeyItem): DeletedKey { @@ -1106,7 +1105,7 @@ export class KeyClient { /** * @internal - * @ignore + * @hidden * Shapes the exposed {@link KeyProperties} based on a received KeyItem. */ private getKeyPropertiesFromKeyItem(keyItem: KeyItem): KeyProperties { diff --git a/sdk/keyvault/keyvault-keys/src/keysModels.ts b/sdk/keyvault/keyvault-keys/src/keysModels.ts index 0ca0b8626a34..490bddc1b27e 100644 --- a/sdk/keyvault/keyvault-keys/src/keysModels.ts +++ b/sdk/keyvault/keyvault-keys/src/keysModels.ts @@ -9,7 +9,6 @@ import { KeyCurveName } from "./cryptographyClientModels"; * Defines values for KeyOperation. * Possible values include: 'encrypt', 'decrypt', 'sign', 'verify', 'wrapKey', 'unwrapKey', 'import' * @readonly - * @enum {string} */ export type KeyOperation = | "encrypt" @@ -24,7 +23,6 @@ export type KeyOperation = * Defines values for KeyType. * Possible values include: 'EC', 'EC-HSM', 'RSA', 'RSA-HSM', 'oct', "oct-HSM" * @readonly - * @enum {string} */ export type KeyType = "EC" | "EC-HSM" | "RSA" | "RSA-HSM" | "oct" | "oct-HSM"; @@ -96,7 +94,7 @@ export interface JsonWebKey { */ p?: Uint8Array; /** - * RSA secret prime, with p < q. + * RSA secret prime, with `p < q`. */ q?: Uint8Array; /** @@ -215,7 +213,7 @@ export interface KeyProperties { readonly recoveryLevel?: DeletionRecoveryLevel; /** * The retention dates of the softDelete data. - * The value should be >=7 and <=90 when softDelete enabled. + * The value should be `>=7` and `<=90` when softDelete enabled. * **NOTE: This property will not be serialized. It can only be populated by the server.** */ recoverableDays?: number; @@ -458,14 +456,14 @@ export interface PurgeDeletedKeyOptions extends coreHttp.OperationOptions {} /** * @internal - * @ignore + * @hidden * Options for {@link recoverDeletedKey}. */ export interface RecoverDeletedKeyOptions extends coreHttp.OperationOptions {} /** * @internal - * @ignore + * @hidden * Options for {@link deleteKey}. */ export interface DeleteKeyOptions extends coreHttp.OperationOptions {} diff --git a/sdk/keyvault/keyvault-keys/src/localCryptography/algorithms.browser.ts b/sdk/keyvault/keyvault-keys/src/localCryptography/algorithms.browser.ts index d37ba5feed10..cd7ebfe2b69a 100644 --- a/sdk/keyvault/keyvault-keys/src/localCryptography/algorithms.browser.ts +++ b/sdk/keyvault/keyvault-keys/src/localCryptography/algorithms.browser.ts @@ -12,7 +12,7 @@ import { LocalAssertion, LocalSupportedAlgorithmsRecord } from "./models"; /** * @internal - * @ignore + * @hidden * The list of known assertions so far. * Assertions verify that the requirements to execute a local cryptography operation are met. */ @@ -34,7 +34,7 @@ export const localSupportedAlgorithms: LocalSupportedAlgorithmsRecord = { /** * Checks whether a given algorithm name is supported or not. - * @param algorithm string name of the algorithm + * @param algorithm - Name of the algorithm */ export function isLocallySupported(_algorithm: string): boolean { return false; diff --git a/sdk/keyvault/keyvault-keys/src/localCryptography/algorithms.ts b/sdk/keyvault/keyvault-keys/src/localCryptography/algorithms.ts index d26a68a50473..4fd5cbbad0e5 100644 --- a/sdk/keyvault/keyvault-keys/src/localCryptography/algorithms.ts +++ b/sdk/keyvault/keyvault-keys/src/localCryptography/algorithms.ts @@ -32,7 +32,7 @@ import { createHash } from "./hash"; /** * @internal - * @ignore + * @hidden * The list of known assertions so far. * Assertions verify that the requirements to execute a local cryptography operation are met. */ @@ -66,7 +66,7 @@ export const assertions: Record<"keyOps" | "rsa" | "nodeOnly", LocalAssertion> = /** * pipeAssertions allows us to execute a sequence of assertions. - * @param assertions One or more LocalAssertions + * @param assertions - One or more LocalAssertions */ const pipeAssertions = (...assertionsParam: LocalAssertion[]): LocalAssertion => ( ...params @@ -117,7 +117,7 @@ export type SignAlgorithmName = "SHA256" | "SHA384" | "SHA512"; * Since sign algorithms behave almost the same, we're making a generator to save up code. * We receive the sign algorithm, from the list of names in `SignAlgorithmName`, * then we generate a `LocalSupportedAlgorithm` that only create hashes and verifies signatures. - * @param signAlgorithm + * @param signAlgorithm - */ const makeSigner = (signAlgorithm: SignAlgorithmName): LocalSupportedAlgorithm => { return { @@ -153,7 +153,7 @@ export const localSupportedAlgorithms: LocalSupportedAlgorithmsRecord = { /** * Checks whether a given algorithm name is supported or not. - * @param algorithm string name of the algorithm + * @param algorithm - Name of the algorithm */ export function isLocallySupported(algorithm: string): boolean { return !!localSupportedAlgorithms[algorithm as LocalSupportedAlgorithmName]; diff --git a/sdk/keyvault/keyvault-keys/src/localCryptography/conversions.ts b/sdk/keyvault/keyvault-keys/src/localCryptography/conversions.ts index 382db5b17539..11bd56b7f5cd 100644 --- a/sdk/keyvault/keyvault-keys/src/localCryptography/conversions.ts +++ b/sdk/keyvault/keyvault-keys/src/localCryptography/conversions.ts @@ -5,7 +5,7 @@ import { JsonWebKey } from "../keysModels"; /** * @internal - * @ignore + * @hidden * Encodes a length of a packet in DER format */ function encodeLength(length: number): Uint8Array { @@ -22,7 +22,7 @@ function encodeLength(length: number): Uint8Array { /** * @internal - * @ignore + * @hidden * Encodes a buffer for DER, as sets the id to the given id */ function encodeBuffer(buffer: Uint8Array, bufferId: number): Uint8Array { @@ -90,7 +90,7 @@ function formatBase64Sequence(base64Sequence: string): string { /** * @internal - * @ignore + * @hidden * Encode a JWK to PEM format. To do so, it internally repackages the JWK as a DER * that is then encoded as a PEM. */ diff --git a/sdk/keyvault/keyvault-keys/src/localCryptography/hash.browser.ts b/sdk/keyvault/keyvault-keys/src/localCryptography/hash.browser.ts index 01fa15817354..593edd9670b2 100644 --- a/sdk/keyvault/keyvault-keys/src/localCryptography/hash.browser.ts +++ b/sdk/keyvault/keyvault-keys/src/localCryptography/hash.browser.ts @@ -5,7 +5,7 @@ import { LocalCryptographyUnsupportedError } from "./models"; /** * @internal - * @ignore + * @hidden * Use the platform-local hashing functionality */ export async function createHash(_algorithm: string, _data: Uint8Array): Promise { diff --git a/sdk/keyvault/keyvault-keys/src/localCryptography/hash.ts b/sdk/keyvault/keyvault-keys/src/localCryptography/hash.ts index e3d2bf64640e..7a42df86f50e 100644 --- a/sdk/keyvault/keyvault-keys/src/localCryptography/hash.ts +++ b/sdk/keyvault/keyvault-keys/src/localCryptography/hash.ts @@ -5,7 +5,7 @@ import { createHash as cryptoCreateHash } from "crypto"; /** * @internal - * @ignore + * @hidden * Use the platform-local hashing functionality */ export async function createHash(algorithm: string, data: Uint8Array): Promise { diff --git a/sdk/keyvault/keyvault-keys/src/localCryptography/models.ts b/sdk/keyvault/keyvault-keys/src/localCryptography/models.ts index 335daece6983..5c842f65eae8 100644 --- a/sdk/keyvault/keyvault-keys/src/localCryptography/models.ts +++ b/sdk/keyvault/keyvault-keys/src/localCryptography/models.ts @@ -17,11 +17,11 @@ export type LocalCryptographyOperationName = "encrypt" | "wrapKey" | "createHash /** * @internal - * @ignore + * @hidden * Abstract representation of a assertion. * Assertions verify that the requirements to execute a local cryptography operation are met. - * @param key The JSON Web Key that will be used during the local operation. - * @param operationName The name of the operation, as in "encrypt", "decrypt", "sign", etc. + * @param key - The JSON Web Key that will be used during the local operation. + * @param operationName - The name of the operation, as in "encrypt", "decrypt", "sign", etc. */ export type LocalAssertion = ( key?: JsonWebKey, @@ -43,16 +43,16 @@ export type LocalSupportedAlgorithmName = /** * Abstract representation of a Local Cryptography Operation function. - * @param keyPEM The string representation of a PEM key. - * @param data The data used on the cryptography operation, in Buffer type. + * @param keyPEM - The string representation of a PEM key. + * @param data - The data used on the cryptography operation, in Buffer type. */ export type LocalCryptographyOperationFunction = (keyPEM: string, data: Buffer) => Promise; /** * Abstract representation of a Local Cryptography Operation function, this time with an additional signature buffer. - * @param keyPEM The string representation of a PEM key. - * @param data The data used on the cryptography operation, in Buffer type. - * @param signature The signature used on the cryptography operation, in Buffer type. + * @param keyPEM - The string representation of a PEM key. + * @param data - The data used on the cryptography operation, in Buffer type. + * @param signature - The signature used on the cryptography operation, in Buffer type. */ export type LocalCryptographyOperationFunctionWithSignature = ( keyPEM: string, diff --git a/sdk/keyvault/keyvault-keys/src/localCryptographyClient.ts b/sdk/keyvault/keyvault-keys/src/localCryptographyClient.ts index 5bcdf9b25a93..6a029722cf26 100644 --- a/sdk/keyvault/keyvault-keys/src/localCryptographyClient.ts +++ b/sdk/keyvault/keyvault-keys/src/localCryptographyClient.ts @@ -30,8 +30,8 @@ export class LocalCryptographyClient { * let client = new LocalCryptographyClient(jsonWebKey); * let result = await client.encrypt("RSA1_5", Buffer.from("My Message")); * ``` - * @param {LocalSupportedAlgorithmName} algorithm The algorithm to use. - * @param {Uint8Array} plaintext The text to encrypt. + * @param algorithm - The algorithm to use. + * @param plaintext - The text to encrypt. */ public async encrypt( algorithm: LocalSupportedAlgorithmName, @@ -58,9 +58,9 @@ export class LocalCryptographyClient { * let client = new LocalCryptographyClient(jsonWebKey); * let result = await client.wrapKey("RSA1_5", keyToWrap); * ``` - * @param {LocalSupportedAlgorithmName} algorithm The encryption algorithm to use to wrap the given key. - * @param {Uint8Array} key The key to wrap. - * @param {EncryptOptions} [options] Additional options. + * @param algorithm - The encryption algorithm to use to wrap the given key. + * @param key - The key to wrap. + * @param options - Additional options. */ public async wrapKey( algorithm: LocalSupportedAlgorithmName, @@ -79,10 +79,10 @@ export class LocalCryptographyClient { * let client = new LocalCryptographyClient(jsonWebKey, credentials); * let result = await client.verifyData("RS256", signedMessage, signature); * ``` - * @param {KeySignatureAlgorithm} algorithm The algorithm to use to verify with. - * @param {Uint8Array} data The signed block of data to verify. - * @param {Uint8Array} signature The signature to verify the block against. - * @param {EncryptOptions} [options] Additional options. + * @param algorithm - The algorithm to use to verify with. + * @param data - The signed block of data to verify. + * @param signature - The signature to verify the block against. + * @param options - Additional options. */ public async verifyData( algorithm: LocalSupportedAlgorithmName, @@ -117,8 +117,7 @@ export class LocalCryptographyClient { * }; * const client = new LocalCryptographyClient(jsonWebKey); * ``` - * @param key The JsonWebKey to use during cryptography operations. - * @memberof CryptographyClient + * @param key - The JsonWebKey to use during cryptography operations. */ constructor(key: JsonWebKey) { this.key = key; diff --git a/sdk/keyvault/keyvault-keys/src/log.ts b/sdk/keyvault/keyvault-keys/src/log.ts index 34271f3d577d..efe27969cdaa 100644 --- a/sdk/keyvault/keyvault-keys/src/log.ts +++ b/sdk/keyvault/keyvault-keys/src/log.ts @@ -4,6 +4,6 @@ import { createClientLogger } from "@azure/logger"; /** - * The @azure/logger configuration for this package. + * The \@azure/logger configuration for this package. */ export const logger = createClientLogger("keyvault-keys"); diff --git a/sdk/keyvault/keyvault-keys/src/transformations.ts b/sdk/keyvault/keyvault-keys/src/transformations.ts index 05f645d6bdbc..8135a18e347c 100644 --- a/sdk/keyvault/keyvault-keys/src/transformations.ts +++ b/sdk/keyvault/keyvault-keys/src/transformations.ts @@ -7,7 +7,7 @@ import { DeletedKey, KeyVaultKey, JsonWebKey, KeyOperation } from "./keysModels" /** * @internal - * @ignore + * @hidden * Shapes the exposed {@link KeyVaultKey} based on either a received key bundle or deleted key bundle. */ export function getKeyFromKeyBundle( diff --git a/sdk/keyvault/keyvault-keys/test/utils/lro/restore/operation.ts b/sdk/keyvault/keyvault-keys/test/utils/lro/restore/operation.ts index cf3c900aa54f..57b462b2c503 100644 --- a/sdk/keyvault/keyvault-keys/test/utils/lro/restore/operation.ts +++ b/sdk/keyvault/keyvault-keys/test/utils/lro/restore/operation.ts @@ -13,7 +13,7 @@ export interface BeginRestoreKeyBackupOptions extends KeyPollerOptions {} /** * @internal - * @ignore + * @hidden * An interface representing the KeyClient. For internal use. */ export interface TestKeyClientInterface { @@ -52,8 +52,8 @@ export interface RestoreKeyBackupPollOperation extends PollOperation {} /** - * @summary Reaches to the service and updates the restore key's poll operation. - * @param [options] The optional parameters, which are an abortSignal from @azure/abort-controller and a function that triggers the poller's onProgress function. + * Reaches to the service and updates the restore key's poll operation. + * @param options - The optional parameters, which are an abortSignal from \@azure/abort-controller and a function that triggers the poller's onProgress function. */ async function update( this: RestoreKeyBackupPollOperation, @@ -84,14 +84,14 @@ async function update( } /** - * @param [options] The optional parameters, which is only an abortSignal from @azure/abort-controller + * @param options - The optional parameters, which is only an abortSignal from \@azure/abort-controller */ async function cancel(this: RestoreKeyBackupPollOperation): Promise { throw new Error("Canceling the restoration of a key is not supported."); } /** - * @summary Serializes the create key's poll operation + * Serializes the create key's poll operation */ function toString(this: RestoreKeyBackupPollOperation): string { return JSON.stringify({ @@ -100,8 +100,8 @@ function toString(this: RestoreKeyBackupPollOperation): string { } /** - * @summary Builds a create key's poll operation - * @param [state] A poll operation's state, in case the new one is intended to follow up where the previous one was left. + * Builds a create key's poll operation + * @param state - A poll operation's state, in case the new one is intended to follow up where the previous one was left. */ export function makeRestoreKeyBackupPollOperation( state: RestoreKeyBackupPollOperationState diff --git a/sdk/keyvault/keyvault-keys/test/utils/lro/restore/poller.ts b/sdk/keyvault/keyvault-keys/test/utils/lro/restore/poller.ts index 0881e83db0ac..369d8a489dad 100644 --- a/sdk/keyvault/keyvault-keys/test/utils/lro/restore/poller.ts +++ b/sdk/keyvault/keyvault-keys/test/utils/lro/restore/poller.ts @@ -27,7 +27,6 @@ export class RestoreKeyBackupPoller extends Poller< > { /** * Defines how much time the poller is going to wait before making a new request to the service. - * @memberof RestoreKeyBackupPoller */ public intervalInMs: number; @@ -54,7 +53,6 @@ export class RestoreKeyBackupPoller extends Poller< /** * The method used by the poller to wait before attempting to update its operation. - * @memberof RestoreKeyBackupPoller */ async delay(): Promise { return delay(this.intervalInMs); diff --git a/sdk/keyvault/keyvault-keys/tsdoc.json b/sdk/keyvault/keyvault-keys/tsdoc.json new file mode 100644 index 000000000000..81c5a8a2aa2f --- /dev/null +++ b/sdk/keyvault/keyvault-keys/tsdoc.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + "extends": ["../../../tsdoc.json"] +} diff --git a/sdk/keyvault/keyvault-secrets/src/identifier.ts b/sdk/keyvault/keyvault-secrets/src/identifier.ts index ba3087e4ba4a..4102107346d4 100644 --- a/sdk/keyvault/keyvault-secrets/src/identifier.ts +++ b/sdk/keyvault/keyvault-secrets/src/identifier.ts @@ -37,15 +37,15 @@ export interface KeyVaultSecretId { * https://.vault.azure.net/secrets// * * On parsing the above Id, this function returns: - * + *```ts * { * sourceId: "https://.vault.azure.net/secrets//", * vaultUrl: "https://.vault.azure.net", * version: "", * name: "" * } - * - * @param id The Id of the Key Vault Secret. + *``` + * @param id - The Id of the Key Vault Secret. */ export function parseKeyVaultSecretId(id: string): KeyVaultSecretId { const urlParts = id.split("/"); diff --git a/sdk/keyvault/keyvault-secrets/src/index.ts b/sdk/keyvault/keyvault-secrets/src/index.ts index 22656cbcbebf..c086ad64f199 100644 --- a/sdk/keyvault/keyvault-secrets/src/index.ts +++ b/sdk/keyvault/keyvault-secrets/src/index.ts @@ -105,7 +105,7 @@ export class SecretClient { /** * @internal - * @ignore + * @hidden * A reference to the auto-generated KeyVault HTTP client. */ private readonly client: KeyVaultClient; @@ -123,11 +123,10 @@ export class SecretClient { * * let client = new SecretClient(vaultUrl, credentials); * ``` - * @param {string} vaultUrl the base URL to the vault. - * @param {TokenCredential} credential An object that implements the `TokenCredential` interface used to authenticate requests to the service. Use the @azure/identity package to create a credential that suits your needs. - * @param {PipelineOptions} [pipelineOptions] Optional. Pipeline options used to configure Key Vault API requests. - * Omit this parameter to use the default pipeline configuration. - * @memberof SecretClient + * @param vaultUrl - The base URL to the vault. + * @param credential - An object that implements the `TokenCredential` interface used to authenticate requests to the service. Use the \@azure/identity package to create a credential that suits your needs. + * @param pipelineOptions - Pipeline options used to configure Key Vault API requests. + * Omit this parameter to use the default pipeline configuration. */ constructor( vaultUrl: string, @@ -179,10 +178,10 @@ export class SecretClient { * let client = new SecretClient(url, credentials); * await client.setSecret("MySecretName", "ABC123"); * ``` - * @summary Adds a secret in a specified key vault. - * @param {string} secretName The name of the secret. - * @param {string} value The value of the secret. - * @param {SetSecretOptions} [options] The optional parameters. + * Adds a secret in a specified key vault. + * @param secretName - The name of the secret. + * @param value - The value of the secret. + * @param options - The optional parameters. */ public async setSecret( secretName: string, @@ -251,9 +250,9 @@ export class SecretClient { * const deletedSecret = await deletePoller.pollUntilDone(); * console.log(deletedSecret); * ``` - * @summary Deletes a secret from a specified key vault. - * @param {string} secretName The name of the secret. - * @param {BeginDeleteSecretOptions} [options] The optional parameters. + * Deletes a secret from a specified key vault. + * @param secretName - The name of the secret. + * @param options - The optional parameters. */ public async beginDeleteSecret( name: string, @@ -284,10 +283,10 @@ export class SecretClient { * let secret = await client.getSecret(secretName); * await client.updateSecretProperties(secretName, secret.properties.version, { enabled: false }); * ``` - * @summary Updates the attributes associated with a specified secret in a given key vault. - * @param {string} secretName The name of the secret. - * @param {string} secretVersion The version of the secret. - * @param {UpdateSecretPropertiesOptions} [options] The optional parameters. + * Updates the attributes associated with a specified secret in a given key vault. + * @param secretName - The name of the secret. + * @param secretVersion - The version of the secret. + * @param options - The optional parameters. */ public async updateSecretProperties( secretName: string, @@ -343,9 +342,9 @@ export class SecretClient { * let client = new SecretClient(url, credentials); * let secret = await client.getSecret("MySecretName"); * ``` - * @summary Get a specified secret from a given key vault. - * @param {string} secretName The name of the secret. - * @param {GetSecretOptions} [options] The optional parameters. + * Get a specified secret from a given key vault. + * @param secretName - The name of the secret. + * @param options - The optional parameters. */ public async getSecret( secretName: string, @@ -378,9 +377,9 @@ export class SecretClient { * let client = new SecretClient(url, credentials); * await client.getDeletedSecret("MyDeletedSecret"); * ``` - * @summary Gets the specified deleted secret. - * @param {string} secretName The name of the secret. - * @param {GetDeletedSecretOptions} [options] The optional parameters. + * Gets the specified deleted secret. + * @param secretName - The name of the secret. + * @param options - The optional parameters. */ public async getDeletedSecret( secretName: string, @@ -416,9 +415,9 @@ export class SecretClient { * await deletePoller.pollUntilDone(); * await client.purgeDeletedSecret("MySecretName"); * ``` - * @summary Permanently deletes the specified secret. - * @param {string} secretName The name of the secret. - * @param {PurgeDeletedSecretOptions} [options] The optional parameters. + * Permanently deletes the specified secret. + * @param secretName - The name of the secret. + * @param options - The optional parameters. */ public async purgeDeletedSecret( secretName: string, @@ -464,9 +463,9 @@ export class SecretClient { * const deletedSecret = await recoverPoller.pollUntilDone(); * console.log(deletedSecret); * ``` - * @summary Recovers the deleted secret to the latest version. - * @param {string} secretName The name of the deleted secret. - * @param {BeginRecoverDeletedSecretOptions} [options] The optional parameters. + * Recovers the deleted secret to the latest version. + * @param secretName - The name of the deleted secret. + * @param options - The optional parameters. */ public async beginRecoverDeletedSecret( name: string, @@ -496,9 +495,9 @@ export class SecretClient { * let client = new SecretClient(url, credentials); * let backupResult = await client.backupSecret("MySecretName"); * ``` - * @summary Backs up the specified secret. - * @param {string} secretName The name of the secret. - * @param {BackupSecretOptions} [options] The optional parameters. + * Backs up the specified secret. + * @param secretName - The name of the secret. + * @param options - The optional parameters. */ public async backupSecret( secretName: string, @@ -532,9 +531,9 @@ export class SecretClient { * // ... * await client.restoreSecretBackup(mySecretBundle); * ``` - * @summary Restores a backed up secret to a vault. - * @param {Uint8Array} secretBundleBackup The backup blob associated with a secret bundle. - * @param {RestoreSecretResponse} [options] The optional parameters. + * Restores a backed up secret to a vault. + * @param secretBundleBackup - The backup blob associated with a secret bundle. + * @param options - The optional parameters. */ public async restoreSecretBackup( secretBundleBackup: Uint8Array, @@ -560,11 +559,11 @@ export class SecretClient { /** * @internal - * @ignore + * @hidden * Deals with the pagination of {@link listPropertiesOfSecretVersions}. - * @param {string} name The name of the KeyVault Secret. - * @param {PageSettings} continuationState An object that indicates the position of the paginated request. - * @param {ListPropertiesOfSecretVersionsOptions} [options] Optional parameters for the underlying HTTP request. + * @param name - The name of the KeyVault Secret. + * @param continuationState - An object that indicates the position of the paginated request. + * @param options - Optional parameters for the underlying HTTP request. */ private async *listPropertiesOfSecretVersionsPage( secretName: string, @@ -607,10 +606,10 @@ export class SecretClient { /** * @internal - * @ignore + * @hidden * Deals with the iteration of all the available results of {@link listPropertiesOfSecretVersions}. - * @param {string} name The name of the KeyVault Secret. - * @param {ListPropertiesOfSecretVersionsOptions} [options] Optional parameters for the underlying HTTP request. + * @param name - The name of the KeyVault Secret. + * @param options - Optional parameters for the underlying HTTP request. */ private async *listPropertiesOfSecretVersionsAll( secretName: string, @@ -637,8 +636,8 @@ export class SecretClient { * console.log("secret version: ", secret); * } * ``` - * @param {string} secretName Name of the secret to fetch versions for. - * @param {ListPropertiesOfSecretVersionsOptions} [options] The optional parameters. + * @param secretName - Name of the secret to fetch versions for. + * @param options - The optional parameters. */ public listPropertiesOfSecretVersions( secretName: string, @@ -668,10 +667,10 @@ export class SecretClient { /** * @internal - * @ignore + * @hidden * Deals with the pagination of {@link listPropertiesOfSecrets}. - * @param {PageSettings} continuationState An object that indicates the position of the paginated request. - * @param {ListPropertiesOfSecretsOptions} [options] Optional parameters for the underlying HTTP request. + * @param continuationState - An object that indicates the position of the paginated request. + * @param options - Optional parameters for the underlying HTTP request. */ private async *listPropertiesOfSecretsPage( continuationState: PageSettings, @@ -708,9 +707,9 @@ export class SecretClient { /** * @internal - * @ignore + * @hidden * Deals with the iteration of all the available results of {@link listPropertiesOfSecrets}. - * @param {ListPropertiesOfSecretsOptions} [options] Optional parameters for the underlying HTTP request. + * @param options - Optional parameters for the underlying HTTP request. */ private async *listPropertiesOfSecretsAll( options: ListPropertiesOfSecretsOptions = {} @@ -736,8 +735,8 @@ export class SecretClient { * console.log("secret: ", secret); * } * ``` - * @summary List all secrets in the vault. - * @param {ListPropertiesOfSecretsOptions} [options] The optional parameters. + * List all secrets in the vault. + * @param options - The optional parameters. */ public listPropertiesOfSecrets( options: ListPropertiesOfSecretsOptions = {} @@ -766,10 +765,10 @@ export class SecretClient { /** * @internal - * @ignore + * @hidden * Deals with the pagination of {@link listDeletedSecrets}. - * @param {PageSettings} continuationState An object that indicates the position of the paginated request. - * @param {ListDeletedSecretsOptions} [options] Optional parameters for the underlying HTTP request. + * @param continuationState - An object that indicates the position of the paginated request. + * @param options - Optional parameters for the underlying HTTP request. */ private async *listDeletedSecretsPage( continuationState: PageSettings, @@ -805,9 +804,9 @@ export class SecretClient { /** * @internal - * @ignore + * @hidden * Deals with the iteration of all the available results of {@link listDeletedSecrets}. - * @param {ListDeletedSecretsOptions} [options] Optional parameters for the underlying HTTP request. + * @param options - Optional parameters for the underlying HTTP request. */ private async *listDeletedSecretsAll( options: ListDeletedSecretsOptions = {} @@ -832,8 +831,8 @@ export class SecretClient { * console.log("deleted secret: ", deletedSecret); * } * ``` - * @summary List all secrets in the vault. - * @param {ListDeletedSecretsOptions} [options] The optional parameters. + * List all secrets in the vault. + * @param options - The optional parameters. */ public listDeletedSecrets( options: ListDeletedSecretsOptions = {} diff --git a/sdk/keyvault/keyvault-secrets/src/log.ts b/sdk/keyvault/keyvault-secrets/src/log.ts index 3ccbd2a4917d..a2919e249071 100644 --- a/sdk/keyvault/keyvault-secrets/src/log.ts +++ b/sdk/keyvault/keyvault-secrets/src/log.ts @@ -4,6 +4,6 @@ import { createClientLogger } from "@azure/logger"; /** - * The @azure/logger configuration for this package. + * The \@azure/logger configuration for this package. */ export const logger = createClientLogger("keyvault-secrets"); diff --git a/sdk/keyvault/keyvault-secrets/src/lro/keyVaultSecretPoller.ts b/sdk/keyvault/keyvault-secrets/src/lro/keyVaultSecretPoller.ts index 951f8250f3af..541ade743de5 100644 --- a/sdk/keyvault/keyvault-secrets/src/lro/keyVaultSecretPoller.ts +++ b/sdk/keyvault/keyvault-secrets/src/lro/keyVaultSecretPoller.ts @@ -71,23 +71,23 @@ export class KeyVaultSecretPollOperation< } /** - * @summary Meant to reach to the service and update the Poller operation. - * @param [options] The optional parameters, which is only an abortSignal from @azure/abort-controller + * Meant to reach to the service and update the Poller operation. + * @param options - The optional parameters, which is only an abortSignal from \@azure/abort-controller */ public async update(): Promise> { throw new Error("Operation not supported."); } /** - * @summary Meant to reach to the service and cancel the Poller operation. - * @param [options] The optional parameters, which is only an abortSignal from @azure/abort-controller + * Meant to reach to the service and cancel the Poller operation. + * @param options - The optional parameters, which is only an abortSignal from \@azure/abort-controller */ public async cancel(): Promise> { throw new Error(this.cancelMessage); } /** - * @summary Serializes the Poller operation. + * Serializes the Poller operation. */ public toString(): string { return JSON.stringify({ diff --git a/sdk/keyvault/keyvault-secrets/src/secretsModels.ts b/sdk/keyvault/keyvault-secrets/src/secretsModels.ts index f86521f3617c..526c1407fe08 100644 --- a/sdk/keyvault/keyvault-secrets/src/secretsModels.ts +++ b/sdk/keyvault/keyvault-secrets/src/secretsModels.ts @@ -119,7 +119,7 @@ export interface SecretProperties { readonly recoveryLevel?: DeletionRecoveryLevel; /** * The retention dates of the softDelete data. - * The value should be >=7 and <=90 when softDelete enabled. + * The value should be `>=7` and `<=90` when softDelete enabled. * **NOTE: This property will not be serialized. It can only be populated by the server.** */ recoverableDays?: number; @@ -274,14 +274,14 @@ export interface RestoreSecretBackupOptions extends coreHttp.OperationOptions {} /** * @internal - * @ignore + * @hidden * Options for {@link recoverDeletedSecret}. */ export interface RecoverDeletedSecretOptions extends coreHttp.OperationOptions {} /** * @internal - * @ignore + * @hidden * Options for {@link deleteSecret}. */ export interface DeleteSecretOptions extends coreHttp.OperationOptions {} diff --git a/sdk/keyvault/keyvault-secrets/src/transformations.ts b/sdk/keyvault/keyvault-secrets/src/transformations.ts index 99bc19497e57..35b7e1c93429 100644 --- a/sdk/keyvault/keyvault-secrets/src/transformations.ts +++ b/sdk/keyvault/keyvault-secrets/src/transformations.ts @@ -7,7 +7,7 @@ import { DeletedSecret, KeyVaultSecret } from "./secretsModels"; /** * @internal - * @ignore + * @hidden * Shapes the exposed {@link KeyVaultKey} based on either a received secret bundle or deleted secret bundle. */ export function getSecretFromSecretBundle( diff --git a/sdk/keyvault/keyvault-secrets/test/utils/lro/restore/operation.ts b/sdk/keyvault/keyvault-secrets/test/utils/lro/restore/operation.ts index 0de01d54cdca..e1cd5591e631 100644 --- a/sdk/keyvault/keyvault-secrets/test/utils/lro/restore/operation.ts +++ b/sdk/keyvault/keyvault-secrets/test/utils/lro/restore/operation.ts @@ -13,7 +13,7 @@ export interface BeginRestoreSecretBackupOptions extends SecretPollerOptions {} /** * @internal - * @ignore + * @hidden * An interface representing the SecretClient. For internal use. */ export interface TestSecretClientInterface { @@ -53,8 +53,8 @@ export interface RestoreSecretBackupPollOperation extends PollOperation {} /** - * @summary Reaches to the service and updates the restore secret's poll operation. - * @param [options] The optional parameters, which are an abortSignal from @azure/abort-controller and a function that triggers the poller's onProgress function. + * Reaches to the service and updates the restore secret's poll operation. + * @param options - The optional parameters, which are an abortSignal from \@azure/abort-controller and a function that triggers the poller's onProgress function. */ async function update( this: RestoreSecretBackupPollOperation, @@ -85,14 +85,14 @@ async function update( } /** - * @param [options] The optional parameters, which is only an abortSignal from @azure/abort-controller + * @param options - The optional parameters, which is only an abortSignal from \@azure/abort-controller */ async function cancel(this: RestoreSecretBackupPollOperation): Promise { throw new Error("Canceling the restoration of a secret is not supported."); } /** - * @summary Serializes the create secret's poll operation + * Serializes the create secret's poll operation */ function toString(this: RestoreSecretBackupPollOperation): string { return JSON.stringify({ @@ -101,8 +101,8 @@ function toString(this: RestoreSecretBackupPollOperation): string { } /** - * @summary Builds a create secret's poll operation - * @param [state] A poll operation's state, in case the new one is intended to follow up where the previous one was left. + * Builds a create secret's poll operation + * @param state - A poll operation's state, in case the new one is intended to follow up where the previous one was left. */ export function makeRestoreSecretBackupPollOperation( state: RestoreSecretBackupPollOperationState diff --git a/sdk/keyvault/keyvault-secrets/test/utils/lro/restore/poller.ts b/sdk/keyvault/keyvault-secrets/test/utils/lro/restore/poller.ts index a49a87b380a7..0fa50a54f1cf 100644 --- a/sdk/keyvault/keyvault-secrets/test/utils/lro/restore/poller.ts +++ b/sdk/keyvault/keyvault-secrets/test/utils/lro/restore/poller.ts @@ -27,7 +27,6 @@ export class RestoreSecretBackupPoller extends Poller< > { /** * Defines how much time the poller is going to wait before making a new request to the service. - * @memberof RestoreSecretBackupPoller */ public intervalInMs: number; @@ -54,7 +53,6 @@ export class RestoreSecretBackupPoller extends Poller< /** * The method used by the poller to wait before attempting to update its operation. - * @memberof RestoreSecretBackupPoller */ async delay(): Promise { return delay(this.intervalInMs); diff --git a/sdk/keyvault/keyvault-secrets/tsdoc.json b/sdk/keyvault/keyvault-secrets/tsdoc.json new file mode 100644 index 000000000000..81c5a8a2aa2f --- /dev/null +++ b/sdk/keyvault/keyvault-secrets/tsdoc.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + "extends": ["../../../tsdoc.json"] +} diff --git a/sdk/metricsadvisor/ai-metrics-advisor/src/logger.ts b/sdk/metricsadvisor/ai-metrics-advisor/src/logger.ts index d4c6f41983a6..3bc4413e84dd 100644 --- a/sdk/metricsadvisor/ai-metrics-advisor/src/logger.ts +++ b/sdk/metricsadvisor/ai-metrics-advisor/src/logger.ts @@ -4,6 +4,6 @@ import { createClientLogger } from "@azure/logger"; /** - * The @azure/logger configuration for this package. + * The \@azure/logger configuration for this package. */ export const logger = createClientLogger("metrics-advisor"); diff --git a/sdk/metricsadvisor/ai-metrics-advisor/src/metricsAdvisorAdministrationClient.ts b/sdk/metricsadvisor/ai-metrics-advisor/src/metricsAdvisorAdministrationClient.ts index 7c0a3df6da15..48ea84f25705 100644 --- a/sdk/metricsadvisor/ai-metrics-advisor/src/metricsAdvisorAdministrationClient.ts +++ b/sdk/metricsadvisor/ai-metrics-advisor/src/metricsAdvisorAdministrationClient.ts @@ -135,14 +135,14 @@ export class MetricsAdvisorAdministrationClient { /** * @internal - * @ignore + * @hidden * A reference to service client options. */ private readonly pipeline: ServiceClientOptions; /** * @internal - * @ignore + * @hidden * A reference to the auto-generated MetricsAdvisor HTTP client. */ private readonly client: GeneratedClient; @@ -159,9 +159,9 @@ export class MetricsAdvisorAdministrationClient { * new MetricsAdvisorKeyCredential("", "") * ); * ``` - * @param {string} endpointUrl Url to an Azure Metrics Advisor service endpoint - * @param {MetricsAdvisorKeyCredential} credential Used to authenticate requests to the service. - * @param {MetricsAdvisorAdministrationClientOptions} [options] Used to configure the Metrics Advisor client. + * @param endpointUrl - Url to an Azure Metrics Advisor service endpoint + * @param credential - Used to authenticate requests to the service. + * @param options - Used to configure the Metrics Advisor client. */ constructor( endpointUrl: string, @@ -174,9 +174,9 @@ export class MetricsAdvisorAdministrationClient { } /** - * Adds a new data feed for a specifc data source and provided settings - * @param feed the data feed object to create - * @param options The options parameter. + * Adds a new data feed for a specific data source and provided settings + * @param feed - the data feed object to create + * @param options - The options parameter. */ public async createDataFeed( @@ -274,8 +274,8 @@ export class MetricsAdvisorAdministrationClient { /** * Retrieves data feed for the given data feed id - * @param id id for the data feed to retrieve - * @param options The options parameter. + * @param id - id for the data feed to retrieve + * @param options - The options parameter. */ public async getDataFeed( @@ -353,7 +353,7 @@ export class MetricsAdvisorAdministrationClient { * } * * ``` - * @param options The options parameter. + * @param options - The options parameter. */ public listDataFeeds( @@ -362,13 +362,13 @@ export class MetricsAdvisorAdministrationClient { const iter = this.listItemsOfDataFeeds(options); return { /** - * @member {Promise} [next] The next method, part of the iteration protocol + * The next method, part of the iteration protocol */ next() { return iter.next(); }, /** - * @member {Symbol} [asyncIterator] The connection to the async iterator, part of the iteration protocol + * The connection to the async iterator, part of the iteration protocol */ [Symbol.asyncIterator]() { return this; @@ -386,7 +386,8 @@ export class MetricsAdvisorAdministrationClient { } /** - * @private + * @internal + * @hidden */ private async *listItemsOfDataFeeds( options: ListDataFeedsOptions @@ -399,7 +400,8 @@ export class MetricsAdvisorAdministrationClient { } /** - * @private + * @internal + * @hidden */ private async *listSegmentsOfDataFeeds( options: ListDataFeedsOptions & { maxPageSize?: number }, @@ -453,9 +455,9 @@ export class MetricsAdvisorAdministrationClient { /** * Updates a data feed given its id - * @param dataFeedId id of the data feed to update - * @param patch Input to the update data feed operation {@link DataFeedPatch} - * @param options The options parameter. + * @param dataFeedId - id of the data feed to update + * @param patch - Input to the update data feed operation {@link DataFeedPatch} + * @param options - The options parameter. */ public async updateDataFeed( @@ -517,8 +519,8 @@ export class MetricsAdvisorAdministrationClient { /** * Deletes a data feed for the given data feed id - * @param id id of the data feed to delete - * @param options The options parameter. + * @param id - id of the data feed to delete + * @param options - The options parameter. */ public async deleteDataFeed(id: string, options: OperationOptions = {}): Promise { @@ -543,8 +545,8 @@ export class MetricsAdvisorAdministrationClient { /** * Creates an anomaly detection configuration for a given metric - * @param config The detection configuration object to create - * @param options The options parameter + * @param config - The detection configuration object to create + * @param options - The options parameter */ public async createDetectionConfig( config: Omit, @@ -580,8 +582,8 @@ export class MetricsAdvisorAdministrationClient { /** * Retrieves metric anomaly detection configuration for the given configuration id - * @param id id of the detection configuration to retrieve - * @param options The options parameter. + * @param id - id of the detection configuration to retrieve + * @param options - The options parameter. */ public async getDetectionConfig( @@ -613,9 +615,9 @@ export class MetricsAdvisorAdministrationClient { /** * Updates a metric anomaly detection configuration for the given configuration id - * @param id id of the detection configuration for metric anomaly to update - * @param patch Input to the update anomaly detection configuration operation {@link AnomalyDetectionConfigurationPatch} - * @param options The options parameter. + * @param id - id of the detection configuration for metric anomaly to update + * @param patch - Input to the update anomaly detection configuration operation {@link AnomalyDetectionConfigurationPatch} + * @param options - The options parameter. */ public async updateDetectionConfig( @@ -646,8 +648,8 @@ export class MetricsAdvisorAdministrationClient { /** * Deletes a metric anomaly detection configuration for the given configuration id - * @param id id of the detection configuration to delete - * @param options The options parameter. + * @param id - id of the detection configuration to delete + * @param options - The options parameter. */ public async deleteDetectionConfig( @@ -675,7 +677,7 @@ export class MetricsAdvisorAdministrationClient { /** * Creates anomaly alerting configuration for a given metric - * @param config the alert configuration object to create + * @param config - The alert configuration object to create */ public async createAlertConfig( config: Omit, @@ -711,9 +713,9 @@ export class MetricsAdvisorAdministrationClient { /** * Updates an anomaly alert configuration for the given configuration id - * @param id id of the anomaly alert configuration to update - * @param patch Input to the update anomaly alert configuration operation {@link AnomalyAlertConfigurationPatch} - * @param options The options parameter + * @param id - id of the anomaly alert configuration to update + * @param patch - Input to the update anomaly alert configuration operation {@link AnomalyAlertConfigurationPatch} + * @param options - The options parameter */ public async updateAlertConfig( id: string, @@ -743,8 +745,8 @@ export class MetricsAdvisorAdministrationClient { /** * Retrieves metric anomaly alert configuration for the given configuration id - * @param id id of the anomaly alert configuration to retrieve - * @param options The options parameter. + * @param id - id of the anomaly alert configuration to retrieve + * @param options - The options parameter. */ public async getAlertConfig( @@ -773,8 +775,8 @@ export class MetricsAdvisorAdministrationClient { /** * Deletes metric anomaly alert configuration for the given configuration id - * @param id id of the anomaly alert configuration to delete - * @param options The options parameter. + * @param id - id of the anomaly alert configuration to delete + * @param options - The options parameter. */ public async deleteAlertConfig( @@ -801,7 +803,8 @@ export class MetricsAdvisorAdministrationClient { } /** - * @private + * @internal + * @hidden */ private async *listSegmentsOfAlertingConfigurations( @@ -822,7 +825,8 @@ export class MetricsAdvisorAdministrationClient { } /** - * @private + * @internal + * @hidden */ private async *listItemsOfAlertingConfigurations( @@ -886,8 +890,8 @@ export class MetricsAdvisorAdministrationClient { * } * * ``` - * @param detectionConfigId anomaly detection configuration unique id - * @param options The options parameter. + * @param detectionConfigId - anomaly detection configuration unique id + * @param options - The options parameter. */ public listAlertConfigs( @@ -901,19 +905,19 @@ export class MetricsAdvisorAdministrationClient { const iter = this.listItemsOfAlertingConfigurations(detectionConfigId, options); return { /** - * @member {Promise} [next] The next method, part of the iteration protocol + * The next method, part of the iteration protocol */ next() { return iter.next(); }, /** - * @member {Symbol} [asyncIterator] The connection to the async iterator, part of the iteration protocol + * The connection to the async iterator, part of the iteration protocol */ [Symbol.asyncIterator]() { return this; }, /** - * @member {Function} [byPage] Return an AsyncIterableIterator that works a page at a time + * Returns an AsyncIterableIterator that works a page at a time */ byPage: () => { return this.listSegmentsOfAlertingConfigurations(detectionConfigId, { @@ -926,8 +930,8 @@ export class MetricsAdvisorAdministrationClient { /** * Adds a new hook - * @param hookInfo Information for the new hook consists of the hook type, name, description, external link and hook parameter - * @param options The options parameter. + * @param hookInfo - Information for the new hook consists of the hook type, name, description, external link and hook parameter + * @param options - The options parameter. */ public async createHook( hookInfo: EmailNotificationHook | WebNotificationHook, @@ -970,8 +974,8 @@ export class MetricsAdvisorAdministrationClient { /** * Retrieves hook for the given hook id - * @param id id for the hook to retrieve - * @param options The options parameter. + * @param id - id for the hook to retrieve + * @param options - The options parameter. */ public async getHook(id: string, options: OperationOptions = {}): Promise { @@ -998,7 +1002,8 @@ export class MetricsAdvisorAdministrationClient { } /** - * @private + * @internal + * @hidden */ private async *listSegmentOfHooks( @@ -1042,7 +1047,8 @@ export class MetricsAdvisorAdministrationClient { } /** - * @private + * @internal + * @hidden */ private async *listItemsOfHooks( @@ -1100,7 +1106,7 @@ export class MetricsAdvisorAdministrationClient { * } * * ``` - * @param options The options parameter. + * @param options - The options parameter. */ public listHooks( @@ -1109,19 +1115,19 @@ export class MetricsAdvisorAdministrationClient { const iter = this.listItemsOfHooks(options); return { /** - * @member {Promise} [next] The next method, part of the iteration protocol + * The next method, part of the iteration protocol */ next() { return iter.next(); }, /** - * @member {Symbol} [asyncIterator] The connection to the async iterator, part of the iteration protocol + * The connection to the async iterator, part of the iteration protocol */ [Symbol.asyncIterator]() { return this; }, /** - * @member {Function} [byPage] Return an AsyncIterableIterator that works a page at a time + * @returns An AsyncIterableIterator that works a page at a time */ byPage: (settings: PageSettings = {}) => { return this.listSegmentOfHooks(settings.continuationToken, settings.maxPageSize, options); @@ -1131,9 +1137,9 @@ export class MetricsAdvisorAdministrationClient { /** * Updates hook for the given hook id - * @param id id of the hook to update - * @param patch Input to the update hook of type Email {@link EmailHookPatch} or WebHook {@link WebhookHookPatch} - * @param options The options parameter + * @param id - id of the hook to update + * @param patch - Input to the update hook of type Email {@link EmailHookPatch} or WebHook {@link WebhookHookPatch} + * @param options - The options parameter */ public async updateHook( id: string, @@ -1161,8 +1167,8 @@ export class MetricsAdvisorAdministrationClient { /** * Deletes hook for the given hook id - * @param id id of the hook to delete - * @param options The options parameter + * @param id - id of the hook to delete + * @param options - The options parameter */ public async deleteHook(id: string, options: OperationOptions = {}): Promise { const { span, updatedOptions: finalOptions } = createSpan( @@ -1185,7 +1191,8 @@ export class MetricsAdvisorAdministrationClient { } /** - * @private + * @internal + * @hidden */ private async *listSegmentsOfDetectionConfigurations( @@ -1203,7 +1210,8 @@ export class MetricsAdvisorAdministrationClient { } /** - * @private + * @internal + * @hidden */ private async *listItemsOfDetectionConfigurations( @@ -1268,8 +1276,8 @@ export class MetricsAdvisorAdministrationClient { * } * * ``` - * @param metricId metric id for list of anomaly detection configurations - * @param options The options parameter. + * @param metricId - metric id for list of anomaly detection configurations + * @param options - The options parameter. */ public listDetectionConfigs( @@ -1283,19 +1291,19 @@ export class MetricsAdvisorAdministrationClient { const iter = this.listItemsOfDetectionConfigurations(metricId, options); return { /** - * @member {Promise} [next] The next method, part of the iteration protocol + * The next method, part of the iteration protocol */ next() { return iter.next(); }, /** - * @member {Symbol} [asyncIterator] The connection to the async iterator, part of the iteration protocol + * The connection to the async iterator, part of the iteration protocol */ [Symbol.asyncIterator]() { return this; }, /** - * @member {Function} [byPage] Return an AsyncIterableIterator that works a page at a time + * @returns An AsyncIterableIterator that works a page at a time */ byPage: () => { return this.listSegmentsOfDetectionConfigurations(metricId, { @@ -1308,8 +1316,8 @@ export class MetricsAdvisorAdministrationClient { /** * Retrieves data feed ingestion progress for the given data feed id - * @param dataFeedId data feed id for the ingestion progress to retrieve - * @param options The options parameter. + * @param dataFeedId - data feed id for the ingestion progress to retrieve + * @param options - The options parameter. */ public async getDataFeedIngestionProgress( @@ -1341,7 +1349,8 @@ export class MetricsAdvisorAdministrationClient { } /** - * @private + * @internal + * @hidden */ private async *listSegmentOfIngestionStatus( dataFeedId: string, @@ -1421,7 +1430,8 @@ export class MetricsAdvisorAdministrationClient { } /** - * @private + * @internal + * @hidden */ private async *listItemsOfIngestionStatus( dataFeedId: string, @@ -1489,10 +1499,10 @@ export class MetricsAdvisorAdministrationClient { * } * * ``` - * @param dataFeedId data feed id for list of data feed ingestion status - * @param startTime The start point of time range to query data ingestion status - * @param endTime The end point of time range to query data ingestion status - * @param options The options parameter. + * @param dataFeedId - data feed id for list of data feed ingestion status + * @param startTime - The start point of time range to query data ingestion status + * @param endTime - The end point of time range to query data ingestion status + * @param options - The options parameter. */ public listDataFeedIngestionStatus( @@ -1509,19 +1519,19 @@ export class MetricsAdvisorAdministrationClient { ); return { /** - * @member {Promise} [next] The next method, part of the iteration protocol + * The next method, part of the iteration protocol */ next() { return iter.next(); }, /** - * @member {Symbol} [asyncIterator] The connection to the async iterator, part of the iteration protocol + * The connection to the async iterator, part of the iteration protocol */ [Symbol.asyncIterator]() { return this; }, /** - * @member {Function} [byPage] Return an AsyncIterableIterator that works a page at a time + * @returns an AsyncIterableIterator that works a page at a time */ byPage: (settings: PageSettings = {}) => { return this.listSegmentOfIngestionStatus( @@ -1540,10 +1550,10 @@ export class MetricsAdvisorAdministrationClient { /** * Refreshes or resets data feed ingestion progress for the given data feed id - * @param dataFeedId The data feed id for the ingestion progress to refresh or reset - * @param startTime The start point of time range to query data ingestion status - * @param endTime The end point of time range to query data ingestion status - * @param options The options parameter. + * @param dataFeedId - The data feed id for the ingestion progress to refresh or reset + * @param startTime - The start point of time range to query data ingestion status + * @param endTime - The end point of time range to query data ingestion status + * @param options - The options parameter. */ public async refreshDataFeedIngestion( diff --git a/sdk/metricsadvisor/ai-metrics-advisor/src/metricsAdvisorClient.ts b/sdk/metricsadvisor/ai-metrics-advisor/src/metricsAdvisorClient.ts index abb177e61887..eeec6cb53623 100644 --- a/sdk/metricsadvisor/ai-metrics-advisor/src/metricsAdvisorClient.ts +++ b/sdk/metricsadvisor/ai-metrics-advisor/src/metricsAdvisorClient.ts @@ -183,14 +183,14 @@ export class MetricsAdvisorClient { /** * @internal - * @ignore + * @hidden * A reference to service client options. */ private readonly pipeline: ServiceClientOptions; /** * @internal - * @ignore + * @hidden * A reference to the auto-generated MetricsAdvisor HTTP client. */ private readonly client: GeneratedClient; @@ -207,9 +207,9 @@ export class MetricsAdvisorClient { * new MetricsAdvisorKeyCredential("", "") * ); * ``` - * @param {string} endpointUrl Url to an Azure Metrics Advisor service endpoint - * @param {MetricsAdvisorKeyCredential} credential Used to authenticate requests to the service. - * @param {MetricsAdvisorClientOptions} [options] Used to configure the Metrics Advisor client. + * @param endpointUrl - Url to an Azure Metrics Advisor service endpoint + * @param credential - Used to authenticate requests to the service. + * @param options - Used to configure the Metrics Advisor client. */ constructor( endpointUrl: string, @@ -222,7 +222,8 @@ export class MetricsAdvisorClient { } /** - * @private + * @internal + * @hidden * List alert segments for alerting configuration */ private async *listSegmentOfAlerts( @@ -299,7 +300,8 @@ export class MetricsAdvisorClient { } /** - * @private + * @internal + * @hidden * List alert items for alerting configuration */ private async *listItemsOfAlerts( @@ -374,11 +376,11 @@ export class MetricsAdvisorClient { * } * * ``` - * @param alertConfigId anomaly alerting configuration unique id - * @param startTime The start of time range to query alert items for alerting configuration - * @param endTime The end of time range to query alert items for alerting configuration - * @param timeMode Query time mode - "AnomalyTime" | "CreatedTime" | "ModifiedTime" - * @param options The options parameter. + * @param alertConfigId - Anomaly alerting configuration unique id + * @param startTime - The start of time range to query alert items for alerting configuration + * @param endTime - The end of time range to query alert items for alerting configuration + * @param timeMode - Query time mode - "AnomalyTime" | "CreatedTime" | "ModifiedTime" + * @param options - The options parameter. */ public listAlerts( @@ -397,19 +399,19 @@ export class MetricsAdvisorClient { ); return { /** - * @member {Promise} [next] The next method, part of the iteration protocol + * The next method, part of the iteration protocol */ next() { return iter.next(); }, /** - * @member {Symbol} [asyncIterator] The connection to the async iterator, part of the iteration protocol + * The connection to the async iterator, part of the iteration protocol */ [Symbol.asyncIterator]() { return this; }, /** - * @member {Function} [byPage] Return an AsyncIterableIterator that works a page at a time + * @returns an AsyncIterableIterator that works a page at a time */ byPage: (settings: PageSettings = {}) => { return this.listSegmentOfAlerts( @@ -426,7 +428,8 @@ export class MetricsAdvisorClient { } /** - * @private + * @internal + * @hidden * List anomalies for alerting configuration - segments */ private async *listSegmentsOfAnomaliesForAlert( @@ -506,7 +509,8 @@ export class MetricsAdvisorClient { } /** - * @private + * @internal + * @hidden * listing anomalies for alerting configuration - items */ private async *listItemsOfAnomaliesForAlert( @@ -534,19 +538,19 @@ export class MetricsAdvisorClient { const iter = this.listItemsOfAnomaliesForAlert(alert.alertConfigId, alert.id, options); return { /** - * @member {Promise} [next] The next method, part of the iteration protocol + * The next method, part of the iteration protocol */ next() { return iter.next(); }, /** - * @member {Symbol} [asyncIterator] The connection to the async iterator, part of the iteration protocol + * The connection to the async iterator, part of the iteration protocol */ [Symbol.asyncIterator]() { return this; }, /** - * @member {Function} [byPage] Return an AsyncIterableIterator that works a page at a time + * @returns An AsyncIterableIterator that works a page at a time */ byPage: (settings: PageSettings = {}) => { return this.listSegmentsOfAnomaliesForAlert( @@ -561,7 +565,8 @@ export class MetricsAdvisorClient { } /** - * @private + * @internal + * @hidden * listing incidents for alert - segments */ private async *listSegmentsOfIncidentsForAlert( @@ -642,7 +647,7 @@ export class MetricsAdvisorClient { } /** - * @private + * @internal * listing incidents for alert - items */ private async *listItemsOfIncidentsForAlert( @@ -709,8 +714,8 @@ export class MetricsAdvisorClient { * page = await pages.next(); * } * ``` - * @param alert Anomaly alert containing alertConfigId and id - * @param options The options parameter. + * @param alert - Anomaly alert containing alertConfigId and id + * @param options - The options parameter. */ public listIncidents( alert: AnomalyAlert, @@ -765,10 +770,10 @@ export class MetricsAdvisorClient { * page = await pages.next(); * } * ``` - * @param detectionConfigId Anomaly detection configuration id - * @param startTime The start of time range to query for incidents - * @param endTime The end of time range to query for incidents - * @param options The options parameter. + * @param detectionConfigId - Anomaly detection configuration id + * @param startTime - The start of time range to query for incidents + * @param endTime - The end of time range to query for incidents + * @param options - The options parameter. */ public listIncidents( detectionConfigId: string, @@ -812,19 +817,19 @@ export class MetricsAdvisorClient { const iter = this.listItemsOfIncidentsForAlert(alert.alertConfigId, alert.id, options); return { /** - * @member {Promise} [next] The next method, part of the iteration protocol + * The next method, part of the iteration protocol */ next() { return iter.next(); }, /** - * @member {Symbol} [asyncIterator] The connection to the async iterator, part of the iteration protocol + * The connection to the async iterator, part of the iteration protocol */ [Symbol.asyncIterator]() { return this; }, /** - * @member {Function} [byPage] Return an AsyncIterableIterator that works a page at a time + * @returns An AsyncIterableIterator that works a page at a time */ byPage: (settings: PageSettings = {}) => { return this.listSegmentsOfIncidentsForAlert( @@ -841,11 +846,11 @@ export class MetricsAdvisorClient { /** * Retrieves enriched metric series data for a detection configuration * - * @param detectionConfigId Anomaly detection configuration id - * @param startTime The start of time range to query metric enriched series data - * @param endTime The end of time range to query metric enriched series data - * @param seriesToFilter Series to retrieve their data - * @param options The options parameter. + * @param detectionConfigId - Anomaly detection configuration id + * @param startTime - The start of time range to query metric enriched series data + * @param endTime - The end of time range to query metric enriched series data + * @param seriesToFilter - Series to retrieve their data + * @param options - The options parameter. */ public async getMetricEnrichedSeriesData( detectionConfigId: string, @@ -886,7 +891,8 @@ export class MetricsAdvisorClient { } /** - * @private + * @internal + * @hidden * listing anomalies for detection config - segments */ @@ -977,7 +983,8 @@ export class MetricsAdvisorClient { } /** - * @private + * @internal + * @hidden * listing anomalies for detection config - items */ @@ -1015,19 +1022,19 @@ export class MetricsAdvisorClient { ); return { /** - * @member {Promise} [next] The next method, part of the iteration protocol + * The next method, part of the iteration protocol */ next() { return iter.next(); }, /** - * @member {Symbol} [asyncIterator] The connection to the async iterator, part of the iteration protocol + * The connection to the async iterator, part of the iteration protocol */ [Symbol.asyncIterator]() { return this; }, /** - * @member {Function} [byPage] Return an AsyncIterableIterator that works a page at a time + * @returns An AsyncIterableIterator that works a page at a time */ byPage: (settings: PageSettings = {}) => { return this.listSegmentsOfAnomaliesForDetectionConfig( @@ -1088,8 +1095,8 @@ export class MetricsAdvisorClient { * } * * ``` - * @param alert Anomaly alert containing alertConfigId and id - * @param options The options parameter. + * @param alert - Anomaly alert containing alertConfigId and id + * @param options - The options parameter. */ public listAnomalies( alert: AnomalyAlert, @@ -1145,10 +1152,10 @@ export class MetricsAdvisorClient { * } * * ``` - * @param detectionConfigId Anomaly detection configuration id - * @param startTime The start of time range to query anomalies - * @param endTime The end of time range to query anomalies - * @param options The options parameter. + * @param detectionConfigId - Anomaly detection configuration id + * @param startTime - The start of time range to query anomalies + * @param endTime - The end of time range to query anomalies + * @param options - The options parameter. */ public listAnomalies( detectionConfigId: string, @@ -1319,10 +1326,10 @@ export class MetricsAdvisorClient { * page = await pages.next(); * } * ``` - * @param detectionConfigId Anomaly detection configuration id - * @param startTime The start of time range to query anomalies - * @param endTime The end of time range to query anomalies - * @param options The options parameter. + * @param detectionConfigId - Anomaly detection configuration id + * @param startTime - The start of time range to query anomalies + * @param endTime - The end of time range to query anomalies + * @param options - The options parameter. */ public listDimensionValuesForDetectionConfig( detectionConfigId: string, @@ -1340,19 +1347,19 @@ export class MetricsAdvisorClient { ); return { /** - * @member {Promise} [next] The next method, part of the iteration protocol + * The next method, part of the iteration protocol */ next() { return iter.next(); }, /** - * @member {Symbol} [asyncIterator] The connection to the async iterator, part of the iteration protocol + * The connection to the async iterator, part of the iteration protocol */ [Symbol.asyncIterator]() { return this; }, /** - * @member {Function} [byPage] Return an AsyncIterableIterator that works a page at a time + * @returns An AsyncIterableIterator that works a page at a time */ byPage: (settings: PageSettings = {}) => { return this.listSegmentsOfDimensionValuesForDetectionConfig( @@ -1490,19 +1497,19 @@ export class MetricsAdvisorClient { ); return { /** - * @member {Promise} [next] The next method, part of the iteration protocol + * The next method, part of the iteration protocol */ next() { return iter.next(); }, /** - * @member {Symbol} [asyncIterator] The connection to the async iterator, part of the iteration protocol + * The connection to the async iterator, part of the iteration protocol */ [Symbol.asyncIterator]() { return this; }, /** - * @member {Function} [byPage] Return an AsyncIterableIterator that works a page at a time + * @returns An AsyncIterableIterator that works a page at a time */ byPage: (settings: PageSettings = {}) => { return this.listSegmentsOfIncidentsForDetectionConfig( @@ -1520,9 +1527,9 @@ export class MetricsAdvisorClient { /** * Gets the root causes of an incident. * - * @param detectionConfigId Anomaly detection configuration id - * @param incidentId Incident id - * @param options The options parameter + * @param detectionConfigId - Anomaly detection configuration id + * @param incidentId - Incident id + * @param options - The options parameter */ public async getIncidentRootCauses( detectionConfigId: string, @@ -1567,8 +1574,8 @@ export class MetricsAdvisorClient { /** * Creates a metric feedback. * - * @param feedback content of the feedback - * @param options The options parameter + * @param feedback - Content of the feedback + * @param options - The options parameter */ public async createFeedback( feedback: MetricFeedbackUnion, @@ -1601,9 +1608,9 @@ export class MetricsAdvisorClient { } /** - * Retrives a metric feedback for the given feedback id. - * @param id Id of the feedback to retrieve - * @param options The options parameter + * Retrieves a metric feedback for the given feedback id. + * @param id - Id of the feedback to retrieve + * @param options - The options parameter */ public async getFeedback( id: string, @@ -1762,8 +1769,8 @@ export class MetricsAdvisorClient { * page = await pages.next(); * } * ``` - * @param metricId Metric id - * @param options The options parameter + * @param metricId - Metric id + * @param options - The options parameter */ public listFeedback( metricId: string, @@ -1772,19 +1779,19 @@ export class MetricsAdvisorClient { const iter = this.listItemsOfFeedback(metricId, options); return { /** - * @member {Promise} [next] The next method, part of the iteration protocol + * The next method, part of the iteration protocol */ next() { return iter.next(); }, /** - * @member {Symbol} [asyncIterator] The connection to the async iterator, part of the iteration protocol + * The connection to the async iterator, part of the iteration protocol */ [Symbol.asyncIterator]() { return this; }, /** - * @member {Function} [byPage] Return an AsyncIterableIterator that works a page at a time + * @returns an AsyncIterableIterator that works a page at a time */ byPage: (settings: PageSettings = {}) => { return this.listSegmentsOfFeedback( @@ -1801,11 +1808,11 @@ export class MetricsAdvisorClient { /** * Gets the time series data for a metric - * @param metricId Metric id - * @param startTime The start of the time range to retrieve series data - * @param endTime The end of the time range to retrieve series data - * @param seriesToFilter A list of time series to retrieve their data - * @param options The options parameter + * @param metricId - Metric id + * @param startTime - The start of the time range to retrieve series data + * @param endTime - The end of the time range to retrieve series data + * @param seriesToFilter - A list of time series to retrieve their data + * @param options - The options parameter */ public async getMetricSeriesData( metricId: string, @@ -1962,9 +1969,9 @@ export class MetricsAdvisorClient { * page = await pages.next(); * } * ``` - * @param metricId Metric id - * @param activeSince Definitions of series ingested after this time are returned - * @param options The options parameter. + * @param metricId - Metric id + * @param activeSince - Definitions of series ingested after this time are returned + * @param options - The options parameter. */ public listMetricSeriesDefinitions( metricId: string, @@ -1978,19 +1985,19 @@ export class MetricsAdvisorClient { ); return { /** - * @member {Promise} [next] The next method, part of the iteration protocol + * The next method, part of the iteration protocol */ next() { return iter.next(); }, /** - * @member {Symbol} [asyncIterator] The connection to the async iterator, part of the iteration protocol + * The connection to the async iterator, part of the iteration protocol */ [Symbol.asyncIterator]() { return this; }, /** - * @member {Function} [byPage] Return an AsyncIterableIterator that works a page at a time + * @returns An AsyncIterableIterator that works a page at a time */ byPage: (settings: PageSettings = {}) => { return this.listSegmentsOfMetricSeriesDefinitions( @@ -2118,9 +2125,9 @@ export class MetricsAdvisorClient { * page = await pages.next(); * } * ``` - * @param metricId Anomaly detection configuration id - * @param dimensionName Name of the dimension to list value - * @param options The options parameter. + * @param metricId - Anomaly detection configuration id + * @param dimensionName - Name of the dimension to list value + * @param options - The options parameter. */ public listMetricDimensionValues( metricId: string, dimensionName: string, @@ -2130,19 +2137,19 @@ export class MetricsAdvisorClient { return { /** - * @member {Promise} [next] The next method, part of the iteration protocol + * The next method, part of the iteration protocol */ next() { return iter.next(); }, /** - * @member {Symbol} [asyncIterator] The connection to the async iterator, part of the iteration protocol + * The connection to the async iterator, part of the iteration protocol */ [Symbol.asyncIterator]() { return this; }, /** - * @member {Function} [byPage] Return an AsyncIterableIterator that works a page at a time + * @returns An AsyncIterableIterator that works a page at a time */ byPage: (settings: PageSettings = {}) => { return this.listSegmentsOfMetricDimensionValues( @@ -2293,10 +2300,10 @@ export class MetricsAdvisorClient { * page = await pages.next(); * } * ``` - * @param metricId Metric id - * @param startTime The start of time range to query for enrichment status - * @param endTime The end of time range to query for enrichment status - * @param options The options parameter. + * @param metricId - Metric id + * @param startTime - The start of time range to query for enrichment status + * @param endTime - The end of time range to query for enrichment status + * @param options - The options parameter. */ public listMetricEnrichmentStatus( metricId: string, @@ -2312,19 +2319,19 @@ export class MetricsAdvisorClient { ); return { /** - * @member {Promise} [next] The next method, part of the iteration protocol + * The next method, part of the iteration protocol */ next() { return iter.next(); }, /** - * @member {Symbol} [asyncIterator] The connection to the async iterator, part of the iteration protocol + * The connection to the async iterator, part of the iteration protocol */ [Symbol.asyncIterator]() { return this; }, /** - * @member {Function} [byPage] Return an AsyncIterableIterator that works a page at a time + * @returns An AsyncIterableIterator that works a page at a time */ byPage: (settings: PageSettings = {}) => { return this.listSegmentsOfMetricEnrichmentStatus( diff --git a/sdk/metricsadvisor/ai-metrics-advisor/src/metricsAdvisorKeyCredentialPolicy.ts b/sdk/metricsadvisor/ai-metrics-advisor/src/metricsAdvisorKeyCredentialPolicy.ts index d7724f26b51e..87dcd5a26c96 100644 --- a/sdk/metricsadvisor/ai-metrics-advisor/src/metricsAdvisorKeyCredentialPolicy.ts +++ b/sdk/metricsadvisor/ai-metrics-advisor/src/metricsAdvisorKeyCredentialPolicy.ts @@ -21,8 +21,8 @@ export class MetricsAdvisorKeyCredential { /** * Creates an instance of MetricsAdvisorKeyCredential * - * @param subscriptionKey Subscription access key from the Azure portal - * @param apiKey API key from the Metrics Advisor web portal + * @param subscriptionKey - Subscription access key from the Azure portal + * @param apiKey - API key from the Metrics Advisor web portal */ constructor(readonly subscriptionKey: string, readonly apiKey: string) {} } diff --git a/sdk/metricsadvisor/ai-metrics-advisor/src/models.ts b/sdk/metricsadvisor/ai-metrics-advisor/src/models.ts index d0477fe0ec47..f212a3ff31ba 100644 --- a/sdk/metricsadvisor/ai-metrics-advisor/src/models.ts +++ b/sdk/metricsadvisor/ai-metrics-advisor/src/models.ts @@ -510,8 +510,8 @@ export interface DetectionConditionsCommon { * * For a metric with two dimensions: city and category, Examples include * - * { { city: "Tokyo", category: "Handmade" } } - identifies one time series - * { { city: "Karachi" } } - identifies all time series with city === "Karachi" + * `{ { city: "Tokyo", category: "Handmade" } }` - identifies one time series + * `{ { city: "Karachi" } }` - identifies all time series with city === "Karachi" */ export type DimensionKey = Record; diff --git a/sdk/metricsadvisor/ai-metrics-advisor/src/tracing.ts b/sdk/metricsadvisor/ai-metrics-advisor/src/tracing.ts index 1ff0124bec85..0a54b362ca1a 100644 --- a/sdk/metricsadvisor/ai-metrics-advisor/src/tracing.ts +++ b/sdk/metricsadvisor/ai-metrics-advisor/src/tracing.ts @@ -7,9 +7,10 @@ import { OperationOptions } from "@azure/core-http"; /** * Creates a span using the global tracer. - * @ignore - * @param name The name of the operation being performed. - * @param tracingOptions The options for the underlying http request. + * @internal + * @hidden + * @param name - The name of the operation being performed. + * @param tracingOptions - The options for the underlying http request. */ export function createSpan( operationName: string, diff --git a/sdk/metricsadvisor/ai-metrics-advisor/tsdoc.json b/sdk/metricsadvisor/ai-metrics-advisor/tsdoc.json new file mode 100644 index 000000000000..81c5a8a2aa2f --- /dev/null +++ b/sdk/metricsadvisor/ai-metrics-advisor/tsdoc.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + "extends": ["../../../tsdoc.json"] +} diff --git a/sdk/schemaregistry/schema-registry/src/logger.ts b/sdk/schemaregistry/schema-registry/src/logger.ts index cf370f034e61..c21643aa718c 100644 --- a/sdk/schemaregistry/schema-registry/src/logger.ts +++ b/sdk/schemaregistry/schema-registry/src/logger.ts @@ -4,6 +4,6 @@ import { createClientLogger } from "@azure/logger"; /** - * The @azure/logger configuration for the schema-registry package. + * The \@azure/logger configuration for the schema-registry package. */ export const logger = createClientLogger("schema-registry"); diff --git a/sdk/schemaregistry/schema-registry/src/models.ts b/sdk/schemaregistry/schema-registry/src/models.ts index 5070fdc34061..2396b8631db1 100644 --- a/sdk/schemaregistry/schema-registry/src/models.ts +++ b/sdk/schemaregistry/schema-registry/src/models.ts @@ -88,8 +88,8 @@ export interface SchemaRegistry { * is created at version 1. If schema of specified name exists already in * specified group, schema is created at latest version + 1. * - * @param schema Schema to register. - * @return Registered schema's ID. + * @param schema - Schema to register. + * @returns Registered schema's ID. */ registerSchema(schema: SchemaDescription, options?: RegisterSchemaOptions): Promise; @@ -97,16 +97,16 @@ export interface SchemaRegistry { * Gets the ID of an existing schema with matching name, group, type, and * content. * - * @param schema Schema to match. - * @return Matched schema's ID. + * @param schema - Schema to match. + * @returns Matched schema's ID. */ getSchemaId(schema: SchemaDescription, options?: GetSchemaIdOptions): Promise; /** * Gets an existing schema by ID. * - * @param id Unique schema ID. - * @return Schema with given ID. + * @param id - Unique schema ID. + * @returns Schema with given ID. */ getSchemaById(id: string, options?: GetSchemaByIdOptions): Promise; } diff --git a/sdk/schemaregistry/schema-registry/src/schemaRegistryClient.ts b/sdk/schemaregistry/schema-registry/src/schemaRegistryClient.ts index cb4733cb93b9..811313097e68 100644 --- a/sdk/schemaregistry/schema-registry/src/schemaRegistryClient.ts +++ b/sdk/schemaregistry/schema-registry/src/schemaRegistryClient.ts @@ -30,10 +30,10 @@ export class SchemaRegistryClient implements SchemaRegistry { /** * Creates a new client for Azure Schema Registry service. * - * @param endpoint The Schema Registry service endpoint URL, for example - * https://mynamespace.servicebus.windows.net. - * @param credential Credential to authenticate requests to the service. - * @param options Options to configure API requests to the service. + * @param endpoint - The Schema Registry service endpoint URL, for example + * https://mynamespace.servicebus.windows.net. + * @param credential - Credential to authenticate requests to the service. + * @param options - Options to configure API requests to the service. */ constructor( endpoint: string, @@ -52,8 +52,8 @@ export class SchemaRegistryClient implements SchemaRegistry { * is created at version 1. If schema of specified name exists already in * specified group, schema is created at latest version + 1. * - * @param schema Schema to register. - * @return Registered schema's ID. + * @param schema - Schema to register. + * @returns Registered schema's ID. */ async registerSchema( schema: SchemaDescription, @@ -73,8 +73,8 @@ export class SchemaRegistryClient implements SchemaRegistry { * Gets the ID of an existing schema with matching name, group, type, and * content. * - * @param schema Schema to match. - * @return Matched schema's ID. + * @param schema - Schema to match. + * @returns Matched schema's ID. */ async getSchemaId(schema: SchemaDescription, options?: GetSchemaIdOptions): Promise { const response = await this.client.schema.queryIdByContent( @@ -91,8 +91,8 @@ export class SchemaRegistryClient implements SchemaRegistry { * Gets the ID of an existing schema with matching name, group, type, and * content. * - * @param schema Schema to match. - * @return Matched schema's ID. + * @param schema - Schema to match. + * @returns Matched schema's ID. */ async getSchemaById(id: string, options?: GetSchemaByIdOptions): Promise { const response = await this.client.schema.getById(id, options); diff --git a/sdk/tables/data-tables/src/TableBatch.ts b/sdk/tables/data-tables/src/TableBatch.ts index 6268d3a8d20d..d31398c3aad1 100644 --- a/sdk/tables/data-tables/src/TableBatch.ts +++ b/sdk/tables/data-tables/src/TableBatch.ts @@ -51,9 +51,9 @@ export class TableBatchImpl implements TableBatch { public readonly partitionKey: string; /** - * @param url Tables account url - * @param partitionKey partition key - * @param credential credential to authenticate the batch request + * @param url - Tables account url + * @param partitionKey - partition key + * @param credential - credential to authenticate the batch request */ constructor( url: string, @@ -87,7 +87,7 @@ export class TableBatchImpl implements TableBatch { /** * Adds a createEntity operation to the batch - * @param entity Entity to create + * @param entity - Entity to create */ public createEntity(entity: TableEntity): void { this.checkPartitionKey(entity.partitionKey); @@ -96,10 +96,10 @@ export class TableBatchImpl implements TableBatch { /** * Adds a createEntity operation to the batch per each entity in the entities array - * @param entitites Array of entities to create + * @param entities - Array of entities to create */ - public createEntities(entitites: TableEntity[]): void { - for (const entity of entitites) { + public createEntities(entities: TableEntity[]): void { + for (const entity of entities) { this.checkPartitionKey(entity.partitionKey); this.pendingOperations.push(this.interceptClient.createEntity(entity)); } @@ -107,9 +107,9 @@ export class TableBatchImpl implements TableBatch { /** * Adds a deleteEntity operation to the batch - * @param partitionKey partition key of the entity to delete - * @param rowKey row key of the entity to delete - * @param options options for the delete operation + * @param partitionKey - Partition key of the entity to delete + * @param rowKey - Row key of the entity to delete + * @param options - Options for the delete operation */ public deleteEntity( partitionKey: string, @@ -122,9 +122,9 @@ export class TableBatchImpl implements TableBatch { /** * Adds an updateEntity operation to the batch - * @param entity entity to update - * @param mode update mode (Merge or Replace) - * @param options options for the update operation + * @param entity - Entity to update + * @param mode - Update mode (Merge or Replace) + * @param options - Options for the update operation */ public updateEntity( entity: TableEntity, @@ -245,9 +245,8 @@ function parseBatchResponse(batchResponse: HttpOperationResponse): TableBatchRes /** * Prepares the operation url to be added to the body, removing the SAS token if present - * @export - * @param {string} url Source URL string - * @returns {(string | undefined)} + * @param url - Source URL string + * @returns */ function getSubRequestUrl(url: string): string { const sasTokenParts = ["sv", "ss", "srt", "sp", "se", "st", "spr", "sig"]; @@ -258,7 +257,7 @@ function getSubRequestUrl(url: string): string { /** * This method creates a batch request object that provides functions to build the envelope and body for a batch request - * @param batchGuid Id of the batch + * @param batchGuid - Id of the batch */ export function createInnerBatchRequest(batchGuid: string, changesetId: string): InnerBatchRequest { const HTTP_LINE_ENDING = "\r\n"; diff --git a/sdk/tables/data-tables/src/TableClient.ts b/sdk/tables/data-tables/src/TableClient.ts index a32e55b3f26d..bf719a93f7e3 100644 --- a/sdk/tables/data-tables/src/TableClient.ts +++ b/sdk/tables/data-tables/src/TableClient.ts @@ -68,11 +68,11 @@ export class TableClient { /** * Creates a new instance of the TableClient class. * - * @param {string} url The URL of the service account that is the target of the desired operation., such as + * @param url - The URL of the service account that is the target of the desired operation., such as * "https://myaccount.table.core.windows.net". - * @param {string} tableName the name of the table - * @param {TablesSharedKeyCredential} credential TablesSharedKeyCredential used to authenticate requests. Only Supported for Browsers - * @param {TableClientOptions} options Optional. Options to configure the HTTP pipeline. + * @param tableName - the name of the table + * @param credential - TablesSharedKeyCredential used to authenticate requests. Only Supported for Browsers + * @param options - Optional. Options to configure the HTTP pipeline. * * Example using an account name/key: * @@ -97,11 +97,11 @@ export class TableClient { /** * Creates an instance of TableClient. * - * @param {string} url A Client string pointing to Azure Storage table service, such as - * "https://myaccount.table.core.windows.net". You can append a SAS, - * such as "https://myaccount.table.core.windows.net?sasString". - * @param {string} tableName the name of the table - * @param {TableClientOptions} options Optional. Options to configure the HTTP pipeline. + * @param url - A Client string pointing to Azure Storage table service, such as + * "https://myaccount.table.core.windows.net". You can append a SAS, + * such as "https://myaccount.table.core.windows.net?sasString". + * @param tableName - the name of the table + * @param options - Options to configure the HTTP pipeline. * * Example appending a SAS token: * @@ -170,7 +170,7 @@ export class TableClient { /** * Permanently deletes the current table with all of its entities. - * @param options The options parameters. + * @param options - The options parameters. */ // eslint-disable-next-line @azure/azure-sdk/ts-naming-options public async delete(options: DeleteTableOptions = {}): Promise { @@ -187,7 +187,7 @@ export class TableClient { /** * Creates the current table it it doesn't exist - * @param options The options parameters. + * @param options - The options parameters. */ // eslint-disable-next-line @azure/azure-sdk/ts-naming-options public async create(options: CreateTableOptions = {}): Promise { @@ -204,9 +204,9 @@ export class TableClient { /** * Returns a single entity in the table. - * @param partitionKey The partition key of the entity. - * @param rowKey The row key of the entity. - * @param options The options parameters. + * @param partitionKey - The partition key of the entity. + * @param rowKey - The row key of the entity. + * @param options - The options parameters. */ public async getEntity( partitionKey: string, @@ -240,8 +240,8 @@ export class TableClient { /** * Queries entities in a table. - * @param tableName The name of the table. - * @param options The options parameters. + * @param tableName - The name of the table. + * @param options - The options parameters. */ public listEntities( // eslint-disable-next-line @azure/azure-sdk/ts-naming-options @@ -347,8 +347,8 @@ export class TableClient { /** * Insert entity in the table. - * @param entity The properties for the table entity. - * @param options The options parameters. + * @param entity - The properties for the table entity. + * @param options - The options parameters. */ public async createEntity( entity: TableEntity, @@ -375,9 +375,9 @@ export class TableClient { /** * Deletes the specified entity in the table. - * @param partitionKey The partition key of the entity. - * @param rowKey The row key of the entity. - * @param options The options parameters. + * @param partitionKey - The partition key of the entity. + * @param rowKey - The row key of the entity. + * @param options - The options parameters. */ public async deleteEntity( partitionKey: string, @@ -410,11 +410,11 @@ export class TableClient { /** * Update an entity in the table. - * @param entity The properties of the entity to be updated. - * @param mode The different modes for updating the entity: - * - Merge: Updates an entity by updating the entity's properties without replacing the existing entity. - * - Replace: Updates an existing entity by replacing the entire entity. - * @param options The options parameters. + * @param entity - The properties of the entity to be updated. + * @param mode - The different modes for updating the entity: + * - Merge: Updates an entity by updating the entity's properties without replacing the existing entity. + * - Replace: Updates an existing entity by replacing the entire entity. + * @param options - The options parameters. */ public async updateEntity( entity: TableEntity, @@ -456,12 +456,12 @@ export class TableClient { /** * Upsert an entity in the table. - * @param tableName The name of the table. - * @param entity The properties for the table entity. - * @param mode The different modes for updating the entity: - * - Merge: Updates an entity by updating the entity's properties without replacing the existing entity. - * - Replace: Updates an existing entity by replacing the entire entity. - * @param options The options parameters. + * @param tableName - The name of the table. + * @param entity - The properties for the table entity. + * @param mode - The different modes for updating the entity: + * - Merge: Updates an entity by updating the entity's properties without replacing the existing entity. + * - Replace: Updates an existing entity by replacing the entire entity. + * @param options - The options parameters. */ public async upsertEntity( entity: TableEntity, @@ -503,7 +503,7 @@ export class TableClient { /** * Creates a new Batch to collect sub-operations that can be submitted together via submitBatch - * @param partitionKey partitionKey to which the batch operations will be targetted to + * @param partitionKey - partitionKey to which the batch operations will be targetted to */ // eslint-disable-next-line @azure/azure-sdk/ts-naming-options public createBatch(partitionKey: string): TableBatch { @@ -535,14 +535,14 @@ export class TableClient { * * Creates an instance of TableClient from connection string. * - * @param {string} connectionString Account connection string or a SAS connection string of an Azure storage account. - * [ Note - Account connection string can only be used in NODE.JS runtime. ] - * Account connection string example - - * `DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=accountKey;EndpointSuffix=core.windows.net` - * SAS connection string example - - * `BlobEndpoint=https://myaccount.table.core.windows.net/;QueueEndpoint=https://myaccount.queue.core.windows.net/;FileEndpoint=https://myaccount.file.core.windows.net/;TableEndpoint=https://myaccount.table.core.windows.net/;SharedAccessSignature=sasString` - * @param {TableClientOptions} [options] Options to configure the HTTP pipeline. - * @returns {TableClient} A new TableClient from the given connection string. + * @param connectionString - Account connection string or a SAS connection string of an Azure storage account. + * [ Note - Account connection string can only be used in NODE.JS runtime. ] + * Account connection string example - + * `DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=accountKey;EndpointSuffix=core.windows.net` + * SAS connection string example - + * `BlobEndpoint=https://myaccount.table.core.windows.net/;QueueEndpoint=https://myaccount.queue.core.windows.net/;FileEndpoint=https://myaccount.file.core.windows.net/;TableEndpoint=https://myaccount.table.core.windows.net/;SharedAccessSignature=sasString` + * @param options - Options to configure the HTTP pipeline. + * @returns A new TableClient from the given connection string. */ public static fromConnectionString( connectionString: string, diff --git a/sdk/tables/data-tables/src/TableServiceClient.ts b/sdk/tables/data-tables/src/TableServiceClient.ts index 805c941640bb..313d970f4efd 100644 --- a/sdk/tables/data-tables/src/TableServiceClient.ts +++ b/sdk/tables/data-tables/src/TableServiceClient.ts @@ -49,11 +49,11 @@ export class TableServiceClient { /** * Creates a new instance of the TableServiceClient class. * - * @param {string} url The URL of the service account that is the target of the desired operation., such as - * "https://myaccount.table.core.windows.net". You can append a SAS, - * such as "https://myaccount.table.core.windows.net?sasString". - * @param {TablesSharedKeyCredential} credential TablesSharedKeyCredential used to authenticate requests. Only Supported for Browsers - * @param {TableServiceClientOptions} options Optional. Options to configure the HTTP pipeline. + * @param url - The URL of the service account that is the target of the desired operation., such as + * "https://myaccount.table.core.windows.net". You can append a SAS, + * such as "https://myaccount.table.core.windows.net?sasString". + * @param credential - TablesSharedKeyCredential used to authenticate requests. Only Supported for Browsers + * @param options - Options to configure the HTTP pipeline. * * Example using an account name/key: * @@ -75,10 +75,10 @@ export class TableServiceClient { /** * Creates a new instance of the TableServiceClient class. * - * @param {string} url The URL of the service account that is the target of the desired operation., such as - * "https://myaccount.table.core.windows.net". You can append a SAS, - * such as "https://myaccount.table.core.windows.net?sasString". - * @param {TableServiceClientOptions} options Optional. Options to configure the HTTP pipeline. + * @param url - The URL of the service account that is the target of the desired operation., such as + * "https://myaccount.table.core.windows.net". You can append a SAS, + * such as "https://myaccount.table.core.windows.net?sasString". + * @param options - Options to configure the HTTP pipeline. * Example appending a SAS token: * * ```js @@ -132,7 +132,7 @@ export class TableServiceClient { /** * Retrieves statistics related to replication for the Table service. It is only available on the * secondary location endpoint when read-access geo-redundant replication is enabled for the account. - * @param options The options parameters. + * @param options - The options parameters. */ public getStatistics(options: GetStatisticsOptions = {}): Promise { const { span, updatedOptions } = createSpan("TableServiceClient-getStatistics", options); @@ -149,7 +149,7 @@ export class TableServiceClient { /** * Gets the properties of an account's Table service, including properties for Analytics and CORS * (Cross-Origin Resource Sharing) rules. - * @param options The options parameters. + * @param options - The options parameters. */ public getProperties(options: GetPropertiesOptions = {}): Promise { const { span, updatedOptions } = createSpan("TableServiceClient-getProperties", options); @@ -166,8 +166,8 @@ export class TableServiceClient { /** * Sets properties for an account's Table service endpoint, including properties for Analytics and CORS * (Cross-Origin Resource Sharing) rules. - * @param properties The Table Service properties. - * @param options The options parameters. + * @param properties - The Table Service properties. + * @param options - The options parameters. */ public setProperties( properties: ServiceProperties, @@ -186,8 +186,8 @@ export class TableServiceClient { /** * Creates a new table under the given account. - * @param tableName The name of the table. - * @param options The options parameters. + * @param tableName - The name of the table. + * @param options - The options parameters. */ public createTable( tableName: string, @@ -209,8 +209,8 @@ export class TableServiceClient { /** * Operation permanently deletes the specified table. - * @param tableName The name of the table. - * @param options The options parameters. + * @param tableName - The name of the table. + * @param options - The options parameters. */ public deleteTable( tableName: string, @@ -229,7 +229,7 @@ export class TableServiceClient { /** * Queries tables under the given account. - * @param options The options parameters. + * @param options - The options parameters. */ public listTables( // eslint-disable-next-line @azure/azure-sdk/ts-naming-options @@ -310,8 +310,8 @@ export class TableServiceClient { /** * Retrieves details about any stored access policies specified on the table that may be used with * Shared Access Signatures. - * @param tableName The name of the table. - * @param options The options parameters. + * @param tableName - The name of the table. + * @param options - The options parameters. */ public getAccessPolicy( tableName: string, @@ -330,9 +330,9 @@ export class TableServiceClient { /** * Sets stored access policies for the table that may be used with Shared Access Signatures. - * @param tableName The name of the table. - * @param acl The Access Control List for the table. - * @param options The options parameters. + * @param tableName - The name of the table. + * @param acl - The Access Control List for the table. + * @param options - The options parameters. */ public setAccessPolicy( tableName: string, @@ -353,14 +353,14 @@ export class TableServiceClient { * * Creates an instance of TableServiceClient from connection string. * - * @param {string} connectionString Account connection string or a SAS connection string of an Azure storage account. - * [ Note - Account connection string can only be used in NODE.JS runtime. ] - * Account connection string example - - * `DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=accountKey;EndpointSuffix=core.windows.net` - * SAS connection string example - - * `BlobEndpoint=https://myaccount.table.core.windows.net/;QueueEndpoint=https://myaccount.queue.core.windows.net/;FileEndpoint=https://myaccount.file.core.windows.net/;TableEndpoint=https://myaccount.table.core.windows.net/;SharedAccessSignature=sasString` - * @param {TableServiceClientOptions} [options] Options to configure the HTTP pipeline. - * @returns {TableServiceClient} A new TableServiceClient from the given connection string. + * @param connectionString - Account connection string or a SAS connection string of an Azure storage account. + * [ Note - Account connection string can only be used in NODE.JS runtime. ] + * Account connection string example - + * `DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=accountKey;EndpointSuffix=core.windows.net` + * SAS connection string example - + * `BlobEndpoint=https://myaccount.table.core.windows.net/;QueueEndpoint=https://myaccount.queue.core.windows.net/;FileEndpoint=https://myaccount.file.core.windows.net/;TableEndpoint=https://myaccount.table.core.windows.net/;SharedAccessSignature=sasString` + * @param options - Options to configure the HTTP pipeline. + * @returns A new TableServiceClient from the given connection string. */ public static fromConnectionString( connectionString: string, diff --git a/sdk/tables/data-tables/src/TablesSharedKeyCredential.browser.ts b/sdk/tables/data-tables/src/TablesSharedKeyCredential.browser.ts index 97358597375b..ca1203801b6f 100644 --- a/sdk/tables/data-tables/src/TablesSharedKeyCredential.browser.ts +++ b/sdk/tables/data-tables/src/TablesSharedKeyCredential.browser.ts @@ -4,8 +4,8 @@ export class TablesSharedKeyCredential { /** * Creates an instance of TablesSharedKeyCredential. - * @param {string} accountName - * @param {string} accountKey + * @param accountName - + * @param accountKey - */ constructor(_accountName: string, _accountKey: string) { throw new Error("TablesSharedKeyCredential is only supported in Node.js environment"); diff --git a/sdk/tables/data-tables/src/TablesSharedKeyCredential.ts b/sdk/tables/data-tables/src/TablesSharedKeyCredential.ts index efc330e473e4..e337766c240e 100644 --- a/sdk/tables/data-tables/src/TablesSharedKeyCredential.ts +++ b/sdk/tables/data-tables/src/TablesSharedKeyCredential.ts @@ -19,8 +19,8 @@ export interface TablesSharedKeyCredentialLike extends RequestPolicyFactory { /** * Generates a hash signature for an HTTP request or for a SAS. * - * @param {string} stringToSign - * @returns {string} + * @param stringToSign - + * @returns */ computeHMACSHA256: (stringToSign: string) => string; } @@ -29,9 +29,6 @@ export interface TablesSharedKeyCredentialLike extends RequestPolicyFactory { * ONLY AVAILABLE IN NODE.JS RUNTIME. * * TablesSharedKeyCredential for account key authorization of Azure Tables service. - * - * @export - * @class TablesSharedKeyCredential */ export class TablesSharedKeyCredential implements TablesSharedKeyCredentialLike { /** @@ -41,15 +38,13 @@ export class TablesSharedKeyCredential implements TablesSharedKeyCredentialLike /** * Azure account key; readonly. - * - * @type {Buffer} */ private readonly accountKey: Buffer; /** * Creates an instance of TablesSharedKeyCredential. - * @param {string} accountName - * @param {string} accountKey + * @param accountName - + * @param accountKey - */ constructor(accountName: string, accountKey: string) { this.accountName = accountName; @@ -59,9 +54,9 @@ export class TablesSharedKeyCredential implements TablesSharedKeyCredentialLike /** * Creates a {@link TablesSharedKeyCredentialPolicy} object. * - * @param {RequestPolicy} nextPolicy - * @param {RequestPolicyOptionsLike} options - * @returns {TablesSharedKeyCredentialPolicy} + * @param nextPolicy - + * @param options - + * @returns */ public create( nextPolicy: RequestPolicy, @@ -73,8 +68,8 @@ export class TablesSharedKeyCredential implements TablesSharedKeyCredentialLike /** * Generates a hash signature for an HTTP request or for a SAS. * - * @param {string} stringToSign - * @returns {string} + * @param stringToSign - + * @returns */ public computeHMACSHA256(stringToSign: string): string { return createHmac("sha256", this.accountKey) diff --git a/sdk/tables/data-tables/src/TablesSharedKeyCredentialPolicy.ts b/sdk/tables/data-tables/src/TablesSharedKeyCredentialPolicy.ts index f1f76a3e3742..6ccb1dcf6ee8 100644 --- a/sdk/tables/data-tables/src/TablesSharedKeyCredentialPolicy.ts +++ b/sdk/tables/data-tables/src/TablesSharedKeyCredentialPolicy.ts @@ -15,24 +15,18 @@ import { URL } from "./utils/url"; /** * TablesSharedKeyCredentialPolicy is a policy used to sign HTTP request with a shared key. - * - * @export - * @class TablesSharedKeyCredentialPolicy - * @extends {CredentialPolicy} */ export class TablesSharedKeyCredentialPolicy extends BaseRequestPolicy { /** * Reference to {@link TablesSharedKeyCredential} which generates TablesSharedKeyCredentialPolicy - * - * @type {TablesSharedKeyCredential} */ private readonly credential: TablesSharedKeyCredentialLike; /** * Creates an instance of TablesSharedKeyCredentialPolicy. - * @param {RequestPolicy} nextPolicy - * @param {RequestPolicyOptions} options - * @param {TablesSharedKeyCredential} factory + * @param nextPolicy - + * @param options - + * @param factory - */ constructor( nextPolicy: RequestPolicy, @@ -46,8 +40,8 @@ export class TablesSharedKeyCredentialPolicy extends BaseRequestPolicy { /** * Sends out request. * - * @param {WebResource} request - * @returns {Promise} + * @param request - + * @returns */ public sendRequest(request: WebResourceLike): Promise { return this._nextPolicy.sendRequest(this.signRequest(request)); @@ -56,9 +50,8 @@ export class TablesSharedKeyCredentialPolicy extends BaseRequestPolicy { /** * Signs request. * - * @protected - * @param {WebResource} request - * @returns {WebResource} + * @param request - + * @returns */ public signRequest(request: WebResourceLike): WebResource { const headerValue = getAuthorizationHeader(request, this.credential); diff --git a/sdk/tables/data-tables/src/logger.ts b/sdk/tables/data-tables/src/logger.ts index 0cf4c687e6d8..e11e4ffee910 100644 --- a/sdk/tables/data-tables/src/logger.ts +++ b/sdk/tables/data-tables/src/logger.ts @@ -4,6 +4,6 @@ import { createClientLogger, AzureLogger } from "@azure/logger"; /** - * The @azure/logger configuration for this package. + * The \@azure/logger configuration for this package. */ export const logger: AzureLogger = createClientLogger("data-tables"); diff --git a/sdk/tables/data-tables/src/models.ts b/sdk/tables/data-tables/src/models.ts index a42839358d5d..c56831f9e222 100644 --- a/sdk/tables/data-tables/src/models.ts +++ b/sdk/tables/data-tables/src/models.ts @@ -426,26 +426,26 @@ export interface TableBatch { partitionKey: string; /** * Adds a createEntity operation to the batch per each entity in the entities array - * @param entitites Array of entities to create + * @param entities - Array of entities to create */ createEntities: (entitites: TableEntity[]) => void; /** * Adds a createEntity operation to the batch - * @param entity Entity to create + * @param entity - Entity to create */ createEntity: (entity: TableEntity) => void; /** * Adds a deleteEntity operation to the batch - * @param partitionKey partition key of the entity to delete - * @param rowKey row key of the entity to delete - * @param options options for the delete operation + * @param partitionKey - Partition key of the entity to delete + * @param rowKey - Row key of the entity to delete + * @param options - Options for the delete operation */ deleteEntity: (partitionKey: string, rowKey: string, options?: DeleteTableEntityOptions) => void; /** * Adds an updateEntity operation to the batch - * @param entity entity to update - * @param mode update mode (Merge or Replace) - * @param options options for the update operation + * @param entity - Entity to update + * @param mode - Update mode (Merge or Replace) + * @param options - Options for the update operation */ updateEntity: ( entity: TableEntity, diff --git a/sdk/tables/data-tables/src/utils/accountConnectionString.browser.ts b/sdk/tables/data-tables/src/utils/accountConnectionString.browser.ts index 82f446ebcd67..629792dc47c2 100644 --- a/sdk/tables/data-tables/src/utils/accountConnectionString.browser.ts +++ b/sdk/tables/data-tables/src/utils/accountConnectionString.browser.ts @@ -7,8 +7,8 @@ import { ConnectionString } from "./internalModels"; /** * Gets client parameters from an Account Connection String * Only supported in Node.js not supported for Browsers - * @param _extractedCreds parsed connection string - * @param _options TablesServiceClient options + * @param _extractedCreds - parsed connection string + * @param _options - TablesServiceClient options */ // eslint-disable-next-line @typescript-eslint/explicit-function-return-type, @typescript-eslint/explicit-module-boundary-types export function fromAccountConnectionString( diff --git a/sdk/tables/data-tables/src/utils/accountConnectionString.ts b/sdk/tables/data-tables/src/utils/accountConnectionString.ts index 391af0311deb..c48a61ced5d6 100644 --- a/sdk/tables/data-tables/src/utils/accountConnectionString.ts +++ b/sdk/tables/data-tables/src/utils/accountConnectionString.ts @@ -9,8 +9,8 @@ import { createPipelineFromOptions } from "@azure/core-http"; /** * Gets client parameters from an Account Connection String * Only supported in Node.js not supported for Browsers - * @param extractedCreds parsed connection string - * @param options TablesServiceClient options + * @param extractedCreds - parsed connection string + * @param options - TablesServiceClient options */ export function fromAccountConnectionString( extractedCreds: ConnectionString, diff --git a/sdk/tables/data-tables/src/utils/bufferSerializer.browser.ts b/sdk/tables/data-tables/src/utils/bufferSerializer.browser.ts index b83687ab2dba..cef247907a65 100644 --- a/sdk/tables/data-tables/src/utils/bufferSerializer.browser.ts +++ b/sdk/tables/data-tables/src/utils/bufferSerializer.browser.ts @@ -3,7 +3,7 @@ /** * Encodes a byte array in base64 format. - * @param value the Uint8Aray to encode + * @param value - The Uint8Aray to encode */ export function base64Encode(value: Uint8Array): string { let str = ""; @@ -15,7 +15,7 @@ export function base64Encode(value: Uint8Array): string { /** * Decodes a base64 string into a byte array. - * @param value the base64 string to decode + * @param value - The base64 string to decode */ export function base64Decode(value: string): Uint8Array { const byteString = atob(value); diff --git a/sdk/tables/data-tables/src/utils/bufferSerializer.ts b/sdk/tables/data-tables/src/utils/bufferSerializer.ts index d609de33de75..b3cfe3d173c7 100644 --- a/sdk/tables/data-tables/src/utils/bufferSerializer.ts +++ b/sdk/tables/data-tables/src/utils/bufferSerializer.ts @@ -3,7 +3,7 @@ /** * Encodes a byte array in base64 format. - * @param value the Uint8Aray to encode + * @param value - The Uint8Aray to encode */ export function base64Encode(value: Uint8Array): string { const bufferValue = value instanceof Buffer ? value : Buffer.from(value.buffer); @@ -12,7 +12,7 @@ export function base64Encode(value: Uint8Array): string { /** * Decodes a base64 string into a byte array. - * @param value the base64 string to decode + * @param value - The base64 string to decode */ export function base64Decode(value: string): Uint8Array { return Buffer.from(value, "base64"); diff --git a/sdk/tables/data-tables/src/utils/connectionString.ts b/sdk/tables/data-tables/src/utils/connectionString.ts index 92f2f0ae232f..0ad757591218 100644 --- a/sdk/tables/data-tables/src/utils/connectionString.ts +++ b/sdk/tables/data-tables/src/utils/connectionString.ts @@ -13,8 +13,8 @@ import { URL } from "./url"; * contain: * - Account Connection String: A pipeline to sign the request with a SharedKey * - SAS Connection String: Attach a SAS token to the storage account url for authentication - * @param connectionString connection string to parse - * @param options TableService client options + * @param connectionString - Connection string to parse + * @param options - TableService client options * @returns */ export function getClientParamsFromConnectionString( @@ -39,9 +39,8 @@ export function getClientParamsFromConnectionString( /** * Extracts the parts of an Storage account connection string. * - * @export - * @param {string} connectionString Connection string. - * @returns {ConnectionString} String key value pairs of the storage account's url and credentials. + * @param connectionString - Connection string. + * @returns String key value pairs of the storage account's url and credentials. */ export function extractConnectionStringParts(connectionString: string): ConnectionString { // Matching TableEndpoint in the Account connection string @@ -102,8 +101,8 @@ function getValueInConnString( /** * Extracts account name from the url - * @param {string} url url to extract the account name from - * @returns {string} with the account name + * @param url - URL to extract the account name from + * @returns The account name */ function getAccountNameFromUrl(url: string): string { if (!url) { diff --git a/sdk/tables/data-tables/src/utils/internalModels.ts b/sdk/tables/data-tables/src/utils/internalModels.ts index c15c74d1f901..1e09e2188b8d 100644 --- a/sdk/tables/data-tables/src/utils/internalModels.ts +++ b/sdk/tables/data-tables/src/utils/internalModels.ts @@ -58,7 +58,7 @@ export interface InnerBatchRequest { createPipeline(): RequestPolicyFactory[]; /** * Adds an operation to add to the batch body - * @param request the operation to add + * @param request - The operation to add */ appendSubRequestToBody(request: WebResourceLike): void; /** @@ -81,18 +81,18 @@ export interface TableClientLike { readonly tableName: string; /** * Creates the current table it it doesn't exist - * @param options The options parameters. + * @param options - The options parameters. */ create(options?: CreateTableOptions): Promise; /** * Creates a new Batch to collect sub-operations that can be submitted together via submitBatch - * @param partitionKey partitionKey to which the batch operations will be targetted to + * @param partitionKey - partitionKey to which the batch operations will be targetted to */ createBatch(partitionKey: string): TableBatch; /** * Insert entity in the table. - * @param entity The properties for the table entity. - * @param options The options parameters. + * @param entity - The properties for the table entity. + * @param options - The options parameters. */ createEntity( entity: TableEntity, @@ -100,14 +100,14 @@ export interface TableClientLike { ): Promise; /** * Permanently deletes the current table with all of its entities. - * @param options The options parameters. + * @param options - The options parameters. */ delete(options?: DeleteTableOptions): Promise; /** * Deletes the specified entity in the table. - * @param partitionKey The partition key of the entity. - * @param rowKey The row key of the entity. - * @param options The options parameters. + * @param partitionKey - The partition key of the entity. + * @param rowKey - The row key of the entity. + * @param options - The options parameters. */ deleteEntity( partitionKey: string, @@ -116,9 +116,9 @@ export interface TableClientLike { ): Promise; /** * Returns a single entity in the table. - * @param partitionKey The partition key of the entity. - * @param rowKey The row key of the entity. - * @param options The options parameters. + * @param partitionKey - The partition key of the entity. + * @param rowKey - The row key of the entity. + * @param options - The options parameters. */ getEntity( partitionKey: string, @@ -127,19 +127,19 @@ export interface TableClientLike { ): Promise>; /** * Queries entities in a table. - * @param tableName The name of the table. - * @param options The options parameters. + * @param tableName - The name of the table. + * @param options - The options parameters. */ listEntities( options?: ListTableEntitiesOptions ): PagedAsyncIterableIterator>; /** * Update an entity in the table. - * @param entity The properties of the entity to be updated. - * @param mode The different modes for updating the entity: - * - Merge: Updates an entity by updating the entity's properties without replacing the existing entity. - * - Replace: Updates an existing entity by replacing the entire entity. - * @param options The options parameters. + * @param entity - The properties of the entity to be updated. + * @param mode - The different modes for updating the entity: + * - Merge: Updates an entity by updating the entity's properties without replacing the existing entity. + * - Replace: Updates an existing entity by replacing the entire entity. + * @param options - The options parameters. */ updateEntity( entity: TableEntity, @@ -148,12 +148,12 @@ export interface TableClientLike { ): Promise; /** * Upsert an entity in the table. - * @param tableName The name of the table. - * @param entity The properties for the table entity. - * @param mode The different modes for updating the entity: - * - Merge: Updates an entity by updating the entity's properties without replacing the existing entity. - * - Replace: Updates an existing entity by replacing the entire entity. - * @param options The options parameters. + * @param tableName - The name of the table. + * @param entity - The properties for the table entity. + * @param mode - The different modes for updating the entity: + * - Merge: Updates an entity by updating the entity's properties without replacing the existing entity. + * - Replace: Updates an existing entity by replacing the entire entity. + * @param options - The options parameters. */ upsertEntity( entity: TableEntity, diff --git a/sdk/tables/data-tables/src/utils/tracing.ts b/sdk/tables/data-tables/src/utils/tracing.ts index 16cc38167bda..d26481be7bd7 100644 --- a/sdk/tables/data-tables/src/utils/tracing.ts +++ b/sdk/tables/data-tables/src/utils/tracing.ts @@ -9,9 +9,10 @@ type OperationTracingOptions = OperationOptions["tracingOptions"]; /** * Creates a span using the global tracer. - * @ignore - * @param name The name of the operation being performed. - * @param tracingOptions The options for the underlying http request. + * @internal + * @hidden + * @param name - The name of the operation being performed. + * @param tracingOptions - The options for the underlying http request. */ export function createSpan( operationName: string, diff --git a/sdk/tables/data-tables/tsdoc.json b/sdk/tables/data-tables/tsdoc.json new file mode 100644 index 000000000000..81c5a8a2aa2f --- /dev/null +++ b/sdk/tables/data-tables/tsdoc.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + "extends": ["../../../tsdoc.json"] +} diff --git a/sdk/textanalytics/ai-text-analytics/src/logger.ts b/sdk/textanalytics/ai-text-analytics/src/logger.ts index 22fae73f5aa3..9bddb3825afd 100644 --- a/sdk/textanalytics/ai-text-analytics/src/logger.ts +++ b/sdk/textanalytics/ai-text-analytics/src/logger.ts @@ -4,6 +4,6 @@ import { createClientLogger } from "@azure/logger"; /** - * The @azure/logger configuration for this package. + * The \@azure/logger configuration for this package. */ export const logger = createClientLogger("ai-text-analytics"); diff --git a/sdk/textanalytics/ai-text-analytics/src/lro/poller.ts b/sdk/textanalytics/ai-text-analytics/src/lro/poller.ts index 8c80e03ee6a2..148946cd941b 100644 --- a/sdk/textanalytics/ai-text-analytics/src/lro/poller.ts +++ b/sdk/textanalytics/ai-text-analytics/src/lro/poller.ts @@ -74,19 +74,19 @@ export abstract class AnalysisPollOperation constructor(public state: TState) {} /** - * @summary Meant to reach to the service and update the Poller operation. - * @param [options] The optional parameters, which is only an abortSignal from @azure/abort-controller + * Meant to reach to the service and update the Poller operation. + * @param options - The optional parameters, which is only an abortSignal from \@azure/abort-controller */ public abstract update(): Promise>; /** - * @summary Meant to reach to the service and cancel the Poller operation. - * @param [options] The optional parameters, which is only an abortSignal from @azure/abort-controller + * Meant to reach to the service and cancel the Poller operation. + * @param options - The optional parameters, which is only an abortSignal from \@azure/abort-controller */ public abstract cancel(): Promise>; /** - * @summary Serializes the Poller operation. + * Serializes the Poller operation. */ public toString(): string { return JSON.stringify({ diff --git a/sdk/textanalytics/ai-text-analytics/src/textAnalyticsClient.ts b/sdk/textanalytics/ai-text-analytics/src/textAnalyticsClient.ts index 1b6f90ffafa7..497ae3e9b32b 100644 --- a/sdk/textanalytics/ai-text-analytics/src/textAnalyticsClient.ts +++ b/sdk/textanalytics/ai-text-analytics/src/textAnalyticsClient.ts @@ -118,7 +118,7 @@ export interface AnalyzeSentimentOptions extends TextAnalyticsOperationOptions { * aspect-based sentiment analysis). If set to true, the returned * `SentenceSentiment` objects will have property `mined_opinions` containing * the result of this analysis. - * More information about the feature can be found here: https://docs.microsoft.com/azure/cognitive-services/text-analytics/how-tos/text-analytics-how-to-sentiment-analysis?tabs=version-3-1#opinion-mining + * More information about the feature can be found here: {@link https://docs.microsoft.com/azure/cognitive-services/text-analytics/how-tos/text-analytics-how-to-sentiment-analysis?tabs=version-3-1#opinion-mining} */ includeOpinionMining?: boolean; } @@ -128,7 +128,7 @@ export interface AnalyzeSentimentOptions extends TextAnalyticsOperationOptions { */ export enum PiiEntityDomainType { /** - * See https://aka.ms/tanerpii for more information. + * @see {@link https://aka.ms/tanerpii} for more information. */ PROTECTED_HEALTH_INFORMATION = "PHI" } @@ -140,7 +140,7 @@ export interface RecognizePiiEntitiesOptions extends TextAnalyticsOperationOptio /** * Filters entities to ones only included in the specified domain (e.g., if * set to 'PHI', entities in the Protected Healthcare Information domain will - * only be returned). See https://aka.ms/tanerpii for more information. + * only be returned). @see {@link https://aka.ms/tanerpii} for more information. */ domainFilter?: PiiEntityDomainType; } @@ -173,7 +173,7 @@ export type PiiTask = { /** * Filters entities to ones only included in the specified domain (e.g., if * set to 'PHI', entities in the Protected Healthcare Information domain will - * only be returned). See https://aka.ms/tanerpii for more information. + * only be returned). @see {@link https://aka.ms/tanerpii} for more information. */ domain?: PiiTaskParametersDomain; /** @@ -232,7 +232,6 @@ export class TextAnalyticsClient { /** * @internal - * @ignore * A reference to the auto-generated TextAnalytics HTTP client. */ private readonly client: GeneratedClient; @@ -249,9 +248,9 @@ export class TextAnalyticsClient { * new AzureKeyCredential("") * ); * ``` - * @param {string} endpointUrl The URL to the TextAnalytics endpoint - * @param {TokenCredential | KeyCredential} credential Used to authenticate requests to the service. - * @param {TextAnalyticsClientOptions} [options] Used to configure the TextAnalytics client. + * @param endpointUrl - The URL to the TextAnalytics endpoint + * @param credential - Used to authenticate requests to the service. + * @param options - Used to configure the TextAnalytics client. */ constructor( endpointUrl: string, @@ -298,15 +297,15 @@ export class TextAnalyticsClient { * language as well as a score indicating the model's confidence that the * inferred language is correct. Scores close to 1 indicate high certainty in * the result. 120 languages are supported. - * @param documents A collection of input strings to analyze. - * @param countryHint Indicates the country of origin for all of + * @param documents - A collection of input strings to analyze. + * @param countryHint - Indicates the country of origin for all of * the input strings to assist the text analytics model in predicting * the language they are written in. If unspecified, this value will be * set to the default country hint in `TextAnalyticsClientOptions`. * If set to an empty string, or the string "none", the service will apply a * model where the country is explicitly unset. * The same country hint is applied to all strings in the input collection. - * @param options Optional parameters for the operation. + * @param options - Optional parameters for the operation. */ public async detectLanguage( documents: string[], @@ -319,8 +318,8 @@ export class TextAnalyticsClient { * language as well as a score indicating the model's confidence that the * inferred language is correct. Scores close to 1 indicate high certainty in * the result. 120 languages are supported. - * @param documents A collection of input documents to analyze. - * @param options Optional parameters for the operation. + * @param documents - A collection of input documents to analyze. + * @param options - Optional parameters for the operation. */ public async detectLanguage( documents: DetectLanguageInput[], @@ -386,17 +385,17 @@ export class TextAnalyticsClient { * Runs a predictive model to identify a collection of named entities * in the passed-in input strings, and categorize those entities into types * such as person, location, or organization. For more information on - * available categories, see - * https://docs.microsoft.com/azure/cognitive-services/Text-Analytics/named-entity-types. - * For a list of languages supported by this operation, see - * https://docs.microsoft.com/azure/cognitive-services/text-analytics/language-support. - * @param documents The input strings to analyze. - * @param language The language that all the input strings are + * available categories, @see + * {@link https://docs.microsoft.com/azure/cognitive-services/Text-Analytics/named-entity-types}. + * For a list of languages supported by this operation, @see + * {@link https://docs.microsoft.com/azure/cognitive-services/text-analytics/language-support}. + * @param documents - The input strings to analyze. + * @param language - The language that all the input strings are written in. If unspecified, this value will be set to the default language in `TextAnalyticsClientOptions`. If set to an empty string, the service will apply a model - where the lanuage is explicitly set to "None". - * @param options Optional parameters for the operation. + where the language is explicitly set to "None". + * @param options - Optional parameters for the operation. */ public async recognizeEntities( documents: string[], @@ -408,12 +407,12 @@ export class TextAnalyticsClient { * Runs a predictive model to identify a collection of named entities * in the passed-in input documents, and categorize those entities into types * such as person, location, or organization. For more information on - * available categories, see - * https://docs.microsoft.com/azure/cognitive-services/Text-Analytics/named-entity-types. - * For a list of languages supported by this operation, see - * https://docs.microsoft.com/azure/cognitive-services/text-analytics/language-support. - * @param documents The input documents to analyze. - * @param options Optional parameters for the operation. + * available categories, @see + * {@link https://docs.microsoft.com/azure/cognitive-services/Text-Analytics/named-entity-types}. + * For a list of languages supported by this operation, @see + * {@link https://docs.microsoft.com/azure/cognitive-services/text-analytics/language-support}. + * @param documents - The input documents to analyze. + * @param options - Optional parameters for the operation. */ public async recognizeEntities( documents: TextDocumentInput[], @@ -486,15 +485,15 @@ export class TextAnalyticsClient { * Runs a predictive model to identify the positive, negative, neutral, or mixed * sentiment contained in the input strings, as well as scores indicating * the model's confidence in each of the predicted sentiments. - * For a list of languages supported by this operation, see - * https://docs.microsoft.com/azure/cognitive-services/text-analytics/language-support. - * @param documents The input strings to analyze. - * @param language The language that all the input strings are + * For a list of languages supported by this operation, @see + * {@link https://docs.microsoft.com/azure/cognitive-services/text-analytics/language-support}. + * @param documents - The input strings to analyze. + * @param language - The language that all the input strings are written in. If unspecified, this value will be set to the default language in `TextAnalyticsClientOptions`. If set to an empty string, the service will apply a model where the lanuage is explicitly set to "None". - * @param options Optional parameters for the operation. + * @param options - Optional parameters for the operation. */ public async analyzeSentiment( documents: string[], @@ -505,10 +504,10 @@ export class TextAnalyticsClient { * Runs a predictive model to identify the positive, negative or neutral, or mixed * sentiment contained in the input documents, as well as scores indicating * the model's confidence in each of the predicted sentiments. - * For a list of languages supported by this operation, see - * https://docs.microsoft.com/azure/cognitive-services/text-analytics/language-support. - * @param documents The input documents to analyze. - * @param options Optional parameters for the operation. + * For a list of languages supported by this operation, @see + * {@link https://docs.microsoft.com/azure/cognitive-services/text-analytics/language-support}. + * @param documents - The input documents to analyze. + * @param options - Options for the operation. */ public async analyzeSentiment( documents: TextDocumentInput[], @@ -571,15 +570,15 @@ export class TextAnalyticsClient { /** * Runs a model to identify a collection of significant phrases * found in the passed-in input strings. - * For a list of languages supported by this operation, see - * https://docs.microsoft.com/azure/cognitive-services/text-analytics/language-support. - * @param documents The input strings to analyze. - * @param language The language that all the input strings are + * For a list of languages supported by this operation, @see + * {@link https://docs.microsoft.com/azure/cognitive-services/text-analytics/language-support}. + * @param documents - The input strings to analyze. + * @param language - The language that all the input strings are written in. If unspecified, this value will be set to the default language in `TextAnalyticsClientOptions`. If set to an empty string, the service will apply a model - where the lanuage is explicitly set to "None". - * @param options Optional parameters for the operation. + where the language is explicitly set to "None". + * @param options - Options for the operation. */ public async extractKeyPhrases( documents: string[], @@ -589,10 +588,10 @@ export class TextAnalyticsClient { /** * Runs a model to identify a collection of significant phrases * found in the passed-in input documents. - * For a list of languages supported by this operation, see - * https://docs.microsoft.com/azure/cognitive-services/text-analytics/language-support. - * @param documents The input documents to analyze. - * @param options Optional parameters for the operation. + * For a list of languages supported by this operation, @see + * {@link https://docs.microsoft.com/azure/cognitive-services/text-analytics/language-support}. + * @param documents - The input documents to analyze. + * @param options - Options for the operation. */ public async extractKeyPhrases( documents: TextDocumentInput[], @@ -655,15 +654,15 @@ export class TextAnalyticsClient { * personally identifiable information found in the passed-in input strings, * and categorize those entities into types such as US social security * number, drivers license number, or credit card number. - * For a list of languages supported by this operation, see - * https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/language-support. - * @param inputs The input strings to analyze. - * @param language The language that all the input strings are + * For a list of languages supported by this operation, @see + * {@link https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/language-support}. + * @param inputs - The input strings to analyze. + * @param language - The language that all the input strings are written in. If unspecified, this value will be set to the default language in `TextAnalyticsClientOptions`. If set to an empty string, the service will apply a model - where the lanuage is explicitly set to "None". - * @param options Optional parameters for the operation. + where the language is explicitly set to "None". + * @param options - Options for the operation. */ public async recognizePiiEntities( inputs: string[], @@ -675,10 +674,10 @@ export class TextAnalyticsClient { * personally identifiable information found in the passed-in input documents, * and categorize those entities into types such as US social security * number, drivers license number, or credit card number. - * For a list of languages supported by this operation, see - * https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/language-support. - * @param inputs The input documents to analyze. - * @param options Optional parameters for the operation. + * For a list of languages supported by this operation, @see + * {@link https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/language-support}. + * @param inputs - The input documents to analyze. + * @param options - Optional parameters for the operation. */ public async recognizePiiEntities( inputs: TextDocumentInput[], @@ -732,15 +731,15 @@ export class TextAnalyticsClient { * Runs a predictive model to identify a collection of entities * found in the passed-in input strings, and include information linking the * entities to their corresponding entries in a well-known knowledge base. - * For a list of languages supported by this operation, see - * https://docs.microsoft.com/azure/cognitive-services/text-analytics/language-support. - * @param documents The input strings to analyze. - * @param language The language that all the input strings are + * For a list of languages supported by this operation, @see + * {@link https://docs.microsoft.com/azure/cognitive-services/text-analytics/language-support}. + * @param documents - The input strings to analyze. + * @param language - The language that all the input strings are written in. If unspecified, this value will be set to the default language in `TextAnalyticsClientOptions`. If set to an empty string, the service will apply a model - where the lanuage is explicitly set to "None". - * @param options Optional parameters for the operation. + where the language is explicitly set to "None". + * @param options - Options for the operation. */ public async recognizeLinkedEntities( documents: string[], @@ -751,10 +750,10 @@ export class TextAnalyticsClient { * Runs a predictive model to identify a collection of entities * found in the passed-in input documents, and include information linking the * entities to their corresponding entries in a well-known knowledge base. - * For a list of languages supported by this operation, see - * https://docs.microsoft.com/azure/cognitive-services/text-analytics/language-support. - * @param documents The input documents to analyze. - * @param options Optional parameters for the operation. + * For a list of languages supported by this operation, @see + * {@link https://docs.microsoft.com/azure/cognitive-services/text-analytics/language-support}. + * @param documents - The input documents to analyze. + * @param options - Options for the operation. */ public async recognizeLinkedEntities( documents: TextDocumentInput[], @@ -815,13 +814,13 @@ export class TextAnalyticsClient { /** * Start a healthcare analysis job to recognize healthcare related entities (drugs, conditions, * symptoms, etc) and their relations. - * @param documents Collection of documents to analyze. - * @param language The language that all the input strings are + * @param documents - Collection of documents to analyze. + * @param language - The language that all the input strings are written in. If unspecified, this value will be set to the default language in `TextAnalyticsClientOptions`. If set to an empty string, the service will apply a model - where the lanuage is explicitly set to "None". - * @param options The options parameters. + where the language is explicitly set to "None". + * @param options - Options for the operation. */ async beginAnalyzeHealthcare( documents: string[], @@ -831,8 +830,8 @@ export class TextAnalyticsClient { /** * Start a healthcare analysis job to recognize healthcare related entities (drugs, conditions, * symptoms, etc) and their relations. - * @param documents Collection of documents to analyze. - * @param options The options parameters. + * @param documents - Collection of documents to analyze. + * @param options - Options for the operation. */ async beginAnalyzeHealthcare( documents: TextDocumentInput[], @@ -868,14 +867,14 @@ export class TextAnalyticsClient { /** * Submit a collection of text documents for analysis. Specify one or more unique tasks to be executed. - * @param documents Collection of documents to analyze - * @param tasks Tasks to execute. - * @param language The language that all the input strings are + * @param documents - Collection of documents to analyze + * @param tasks - Tasks to execute. + * @param language - The language that all the input strings are written in. If unspecified, this value will be set to the default language in `TextAnalyticsClientOptions`. If set to an empty string, the service will apply a model - where the lanuage is explicitly set to "None". - * @param options The options parameters. + where the language is explicitly set to "None". + * @param options - Options for the operation. */ public async beginAnalyze( documents: string[], @@ -885,9 +884,9 @@ export class TextAnalyticsClient { ): Promise; /** * Submit a collection of text documents for analysis. Specify one or more unique tasks to be executed. - * @param documents Collection of documents to analyze - * @param tasks Tasks to execute. - * @param options The options parameters. + * @param documents - Collection of documents to analyze + * @param tasks - Tasks to execute. + * @param options - Options for the operation. */ public async beginAnalyze( documents: TextDocumentInput[], diff --git a/sdk/textanalytics/ai-text-analytics/src/textAnalyticsResult.ts b/sdk/textanalytics/ai-text-analytics/src/textAnalyticsResult.ts index 57d56356ddcb..372bb5aa96b6 100644 --- a/sdk/textanalytics/ai-text-analytics/src/textAnalyticsResult.ts +++ b/sdk/textanalytics/ai-text-analytics/src/textAnalyticsResult.ts @@ -168,10 +168,12 @@ export function makeTextAnalyticsErrorResult( } /** + * @internal + * @hidden * combines successful and erroneous results into a single array of results and * sort them so that the IDs order match that of the input documents array. - * @param input the array of documents sent to the service for processing. - * @param response the response received from the service. + * @param input - the array of documents sent to the service for processing. + * @param response - the response received from the service. */ export function combineSuccessfulAndErroneousDocuments( input: TextDocumentInput[], @@ -181,11 +183,13 @@ export function combineSuccessfulAndErroneousDocuments( operationName: string, diff --git a/sdk/textanalytics/ai-text-analytics/src/util.ts b/sdk/textanalytics/ai-text-analytics/src/util.ts index 91bf2e45bdd2..b218b3e7777e 100644 --- a/sdk/textanalytics/ai-text-analytics/src/util.ts +++ b/sdk/textanalytics/ai-text-analytics/src/util.ts @@ -14,9 +14,10 @@ export interface IdObject { * Given a sorted array of input objects (with a unique ID) and an unsorted array of results, * return a sorted array of results. * - * @ignore - * @param sortedArray An array of entries sorted by `id` - * @param unsortedArray An array of entries that contain `id` but are not sorted + * @internal + * @hidden + * @param sortedArray - An array of entries sorted by `id` + * @param unsortedArray - An array of entries that contain `id` but are not sorted */ export function sortResponseIdObjects( sortedArray: T[], @@ -114,9 +115,11 @@ export function getJobID(operationLocation: string): string { } /** + * @internal + * @hidden * parses incoming errors from the service and if the inner error code is * InvalidDocumentBatch, it exposes that as the statusCode instead. - * @param error the incoming error + * @param error - the incoming error */ export function handleInvalidDocumentBatch(error: unknown): any { const castError = error as { diff --git a/sdk/textanalytics/ai-text-analytics/tsdoc.json b/sdk/textanalytics/ai-text-analytics/tsdoc.json new file mode 100644 index 000000000000..81c5a8a2aa2f --- /dev/null +++ b/sdk/textanalytics/ai-text-analytics/tsdoc.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + "extends": ["../../../tsdoc.json"] +} diff --git a/tsdoc.json b/tsdoc.json new file mode 100644 index 000000000000..6e1223d4e138 --- /dev/null +++ b/tsdoc.json @@ -0,0 +1,9 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + "tagDefinitions": [ + { + "tagName": "@hidden", + "syntaxKind": "modifier" + } + ] +}