Standardization of our documentation comments

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",

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"
   }
 };

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,
                     ]);

sdk/anomalydetector/ai-anomaly-detector/src/AnomalyDetectorClient.ts

@@ -44,7 +44,6 @@ export class AnomalyDetectorClient {
 
   /**
    * @internal
-   * @ignore
    * A reference to the auto-generated AnomalyDetector HTTP client.
    */
   private client: GeneratedClient;
@@ -61,9 +60,9 @@ export class AnomalyDetectorClient {
    *    new AzureKeyCredential("<api key>")
    * );
    * ```
-   * @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 +106,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 +137,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 +166,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,

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");

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;
   /**

sdk/anomalydetector/ai-anomaly-detector/src/tracing.ts

@@ -7,9 +7,9 @@ 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
+ * @param name - The name of the operation being performed.
+ * @param tracingOptions - The options for the underlying http request.
  */
 export function createSpan<T extends OperationOptions>(
   operationName: string,

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,19 +112,14 @@ 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);
   }
 
   /**
    * 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();

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,27 +72,21 @@ 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();
   }
 
   /**
    * 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

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;