fix(docs): add plugin-eslint-tsdoc (#4525)

* fix(docs): fix eslint identified tsdoc tags and add eslint-plugin-tsdoc to prevent regression

* fix(pin): pin eslint-plugin-typedoc

package.json

@@ -80,6 +80,7 @@
     "eslint-plugin-prettier": "4.0.0",
     "eslint-plugin-simple-import-sort": "7.0.0",
     "eslint-plugin-sort-export-all": "1.2.2",
+    "eslint-plugin-tsdoc": "0.2.17",
     "esprint": "3.6.0",
     "fastify": "^4.11.0",
     "figlet": "^1.5.0",

packages/smithy-client/.eslintrc.json

@@ -0,0 +1,6 @@
+{
+  "plugins": ["eslint-plugin-tsdoc"],
+  "rules": {
+    "tsdoc/syntax": "warn"
+  }
+}

packages/smithy-client/src/date-utils.ts

@@ -14,11 +14,11 @@ const MONTHS: Array<String> = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul",
  * since not all environments will have this as the expected
  * format.
  *
- * See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toUTCString
- * > Prior to ECMAScript 2018, the format of the return value
- * > varied according to the platform. The most common return
- * > value was an RFC-1123 formatted date stamp, which is a
- * > slightly updated version of RFC-822 date stamps.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toUTCString}
+ * - Prior to ECMAScript 2018, the format of the return value
+ * - varied according to the platform. The most common return
+ * - value was an RFC-1123 formatted date stamp, which is a
+ * - slightly updated version of RFC-822 date stamps.
  */
 export function dateToUtcString(date: Date): string {
   const year = date.getUTCFullYear();
@@ -51,10 +51,10 @@ const RFC3339 = new RegExp(/^(\d{4})-(\d{2})-(\d{2})[tT](\d{2}):(\d{2}):(\d{2})(
  * Input strings must conform to RFC3339 section 5.6, and cannot have a UTC
  * offset. Fractional precision is supported.
  *
- * {@see https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14}
+ * @see {@link https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14}
  *
- * @param value the value to parse
- * @return a Date or undefined
+ * @param value - the value to parse
+ * @returns a Date or undefined
  */
 export const parseRfc3339DateTime = (value: unknown): Date | undefined => {
   if (value === null || value === undefined) {
@@ -91,10 +91,10 @@ const RFC3339_WITH_OFFSET = new RegExp(
  * Input strings must conform to RFC3339 section 5.6, and can have a UTC
  * offset. Fractional precision is supported.
  *
- * {@see https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14}
+ * @see {@link https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14}
  *
- * @param value the value to parse
- * @return a Date or undefined
+ * @param value - the value to parse
+ * @returns a Date or undefined
  */
 export const parseRfc3339DateTimeWithOffset = (value: unknown): Date | undefined => {
   if (value === null || value === undefined) {
@@ -142,10 +142,10 @@ const ASC_TIME = new RegExp(
  *
  * Input strings must conform to RFC7231 section 7.1.1.1. Fractional seconds are supported.
  *
- * {@see https://datatracker.ietf.org/doc/html/rfc7231.html#section-7.1.1.1}
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc7231.html#section-7.1.1.1}
  *
- * @param value the value to parse
- * @return a Date or undefined
+ * @param value - the value to parse
+ * @returns a Date or undefined
  */
 export const parseRfc7231DateTime = (value: unknown): Date | undefined => {
   if (value === null || value === undefined) {
@@ -204,8 +204,8 @@ export const parseRfc7231DateTime = (value: unknown): Date | undefined => {
  *
  * Input strings must be an integer or floating point number. Fractional seconds are supported.
  *
- * @param value the value to parse
- * @return a Date or undefined
+ * @param value - the value to parse
+ * @returns a Date or undefined
  */
 export const parseEpochTimestamp = (value: unknown): Date | undefined => {
   if (value === null || value === undefined) {
@@ -237,10 +237,10 @@ interface RawTime {
 /**
  * Build a date from a numeric year, month, date, and an match with named groups
  * "H", "m", s", and "frac", representing hours, minutes, seconds, and optional fractional seconds.
- * @param year numeric year
- * @param month numeric month, 1-indexed
- * @param day numeric year
- * @param match match with groups "H", "m", s", and "frac"
+ * @param year - numeric year
+ * @param month - numeric month, 1-indexed
+ * @param day - numeric year
+ * @param match - match with groups "H", "m", s", and "frac"
  */
 const buildDate = (year: number, month: number, day: number, time: RawTime): Date => {
   const adjustedMonth = month - 1; // JavaScript, and our internal data structures, expect 0-indexed months
@@ -270,8 +270,8 @@ const buildDate = (year: number, month: number, day: number, time: RawTime): Dat
  * but keep '22' as 2022. in 2099, '11' will represent '2111', but '98' should be '2098'.
  * There's no description of an RFC 850 date being considered too far in the past in RFC-7231,
  * so it's entirely possible that 2011 is a valid interpretation of '11' in 2099.
- * @param value the 2 digit year to parse
- * @return number a year that is equal to or greater than the current UTC year
+ * @param value - the 2 digit year to parse
+ * @returns number a year that is equal to or greater than the current UTC year
  */
 const parseTwoDigitYear = (value: string): number => {
   const thisYear = new Date().getUTCFullYear();
@@ -296,8 +296,8 @@ const FIFTY_YEARS_IN_MILLIS = 50 * 365 * 24 * 60 * 60 * 1000;
  * than 50 years in the future as representing the most recent year in
  * the past that had the same last two digits.</blockquote>
  *
- * @param input a Date that assumes the two-digit year was in the future
- * @return a Date that is in the past if input is > 50 years in the future
+ * @param input - a Date that assumes the two-digit year was in the future
+ * @returns a Date that is in the past if input is \> 50 years in the future
  */
 const adjustRfc850Year = (input: Date): Date => {
   if (input.getTime() - new Date().getTime() > FIFTY_YEARS_IN_MILLIS) {
@@ -328,9 +328,9 @@ const DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
 
 /**
  * Validate the day is valid for the given month.
- * @param year the year
- * @param month the month (0-indexed)
- * @param day the day of the month
+ * @param year - the year
+ * @param month - the month (0-indexed)
+ * @param day - the day of the month
  */
 const validateDayOfMonth = (year: number, month: number, day: number) => {
   let maxDays = DAYS_IN_MONTH[month];

packages/smithy-client/src/default-error-handler.ts

@@ -3,7 +3,7 @@ import { HttpResponse, ResponseMetadata } from "@aws-sdk/types";
 import { decorateServiceException } from "./exceptions";
 
 /**
- * Always throws an error with the given {@param exceptionCtor} and other arguments.
+ * Always throws an error with the given `exceptionCtor` and other arguments.
  * This is only called from an error handling code path.
  *
  * @internal

packages/smithy-client/src/defaults-mode.ts

@@ -38,7 +38,7 @@ export const loadConfigsForDefaultMode = (mode: ResolvedDefaultsMode): DefaultsM
  * * `"auto"`: <p>The AUTO mode is an experimental mode that builds on the standard mode. The SDK will attempt to discover the execution environment to determine the appropriate settings automatically.</p><p>Note that the auto detection is heuristics-based and does not guarantee 100% accuracy. STANDARD mode will be used if the execution environment cannot be determined. The auto detection might query <a href="https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html">EC2 Instance Metadata service</a>, which might introduce latency. Therefore we recommend choosing an explicit defaults_mode instead if startup latency is critical to your application</p>
  * * `"legacy"`: <p>The LEGACY mode provides default settings that vary per SDK and were used prior to establishment of defaults_mode</p>
  *
- * @default "legacy"
+ * @defaultValue "legacy"
  */
 export type DefaultsMode = "standard" | "in-region" | "cross-region" | "mobile" | "auto" | "legacy";
 

packages/smithy-client/src/emitWarningIfUnsupportedVersion.ts

@@ -6,7 +6,7 @@ let warningEmitted = false;
  *
  * Emits warning if the provided Node.js version string is pending deprecation.
  *
- * @param {string} version - The Node.js version string.
+ * @param version - The Node.js version string.
  */
 export const emitWarningIfUnsupportedVersion = (version: string) => {
   if (version && !warningEmitted && parseInt(version.substring(1, version.indexOf("."))) < 14) {

packages/smithy-client/src/object-mapping.ts

@@ -200,7 +200,7 @@ export function map(arg0: any, arg1?: any, arg2?: any): any {
 }
 
 /**
- * Convert a regular object { k: v } to { k: [, v] } mapping instruction set with default
+ * Convert a regular object `{ k: v }` to `{ k: [, v] }` mapping instruction set with default
  * filter.
  *
  * @internal

packages/smithy-client/src/parse-utils.ts

@@ -3,7 +3,7 @@
  *
  * Give an input string, strictly parses a boolean value.
  *
- * @param value The boolean string to parse.
+ * @param value - The boolean string to parse.
  * @returns true for "true", false for "false", otherwise an error is thrown.
  */
 export const parseBoolean = (value: string): boolean => {
@@ -24,7 +24,7 @@ export const parseBoolean = (value: string): boolean => {
  * Casts strings and numbers with a warning if there is evidence that they were
  * intended to be booleans.
  *
- * @param value A value that is expected to be a boolean.
+ * @param value - A value that is expected to be a boolean.
  * @returns The value if it's a boolean, undefined if it's null/undefined,
  *   otherwise an error is thrown.
  */
@@ -68,7 +68,7 @@ export const expectBoolean = (value: any): boolean | undefined => {
  * Casts strings with a warning if the string is a parseable number.
  * This is to unblock slight API definition/implementation inconsistencies.
  *
- * @param value A value that is expected to be a number.
+ * @param value - A value that is expected to be a number.
  * @returns The value if it's a number, undefined if it's null/undefined,
  *   otherwise an error is thrown.
  */
@@ -98,7 +98,7 @@ const MAX_FLOAT = Math.ceil(2 ** 127 * (2 - 2 ** -23));
  *
  * Asserts a value is a 32-bit float and returns it.
  *
- * @param value A value that is expected to be a 32-bit float.
+ * @param value - A value that is expected to be a 32-bit float.
  * @returns The value if it's a float, undefined if it's null/undefined,
  *   otherwise an error is thrown.
  */
@@ -149,7 +149,7 @@ export const expectFloat32 = (value: any): number | undefined => {
  *
  * Asserts a value is an integer and returns it.
  *
- * @param value A value that is expected to be an integer.
+ * @param value - A value that is expected to be an integer.
  * @returns The value if it's an integer, undefined if it's null/undefined,
  *   otherwise an error is thrown.
  */
@@ -175,7 +175,7 @@ export const expectInt = expectLong;
  *
  * Asserts a value is a 32-bit integer and returns it.
  *
- * @param value A value that is expected to be an integer.
+ * @param value - A value that is expected to be an integer.
  * @returns The value if it's an integer, undefined if it's null/undefined,
  *   otherwise an error is thrown.
  */
@@ -186,7 +186,7 @@ export const expectInt32 = (value: any): number | undefined => expectSizedInt(va
  *
  * Asserts a value is a 16-bit integer and returns it.
  *
- * @param value A value that is expected to be an integer.
+ * @param value - A value that is expected to be an integer.
  * @returns The value if it's an integer, undefined if it's null/undefined,
  *   otherwise an error is thrown.
  */
@@ -197,7 +197,7 @@ export const expectShort = (value: any): number | undefined => expectSizedInt(va
  *
  * Asserts a value is an 8-bit integer and returns it.
  *
- * @param value A value that is expected to be an integer.
+ * @param value - A value that is expected to be an integer.
  * @returns The value if it's an integer, undefined if it's null/undefined,
  *   otherwise an error is thrown.
  */
@@ -229,8 +229,8 @@ const castInt = (value: number, size: IntSize) => {
  *
  * Asserts a value is not null or undefined and returns it, or throws an error.
  *
- * @param value A value that is expected to be defined
- * @param location The location where we're expecting to find a defined object (optional)
+ * @param value - A value that is expected to be defined
+ * @param location - The location where we're expecting to find a defined object (optional)
  * @returns The value if it's not undefined, otherwise throws an error
  */
 export const expectNonNull = <T>(value: T | null | undefined, location?: string): T => {
@@ -249,7 +249,7 @@ export const expectNonNull = <T>(value: T | null | undefined, location?: string)
  * Asserts a value is an JSON-like object and returns it. This is expected to be used
  * with values parsed from JSON (arrays, objects, numbers, strings, booleans).
  *
- * @param value A value that is expected to be an object
+ * @param value - A value that is expected to be an object
  * @returns The value if it's an object, undefined if it's null/undefined,
  *   otherwise an error is thrown.
  */
@@ -270,7 +270,7 @@ export const expectObject = (value: any): Record<string, any> | undefined => {
  * Asserts a value is a string and returns it.
  * Numbers and boolean will be cast to strings with a warning.
  *
- * @param value A value that is expected to be a string.
+ * @param value - A value that is expected to be a string.
  * @returns The value if it's a string, undefined if it's null/undefined,
  *   otherwise an error is thrown.
  */
@@ -294,9 +294,9 @@ export const expectString = (value: any): string | undefined => {
  * Asserts a value is a JSON-like object with only one non-null/non-undefined key and
  * returns it.
  *
- * @param value A value that is expected to be an object with exactly one non-null,
+ * @param value - A value that is expected to be an object with exactly one non-null,
  *              non-undefined key.
- * @return the value if it's a union, undefined if it's null/undefined, otherwise
+ * @returns the value if it's a union, undefined if it's null/undefined, otherwise
  *  an error is thrown.
  */
 export const expectUnion = (value: unknown): Record<string, any> | undefined => {
@@ -329,7 +329,7 @@ export const expectUnion = (value: unknown): Record<string, any> | undefined =>
  * "NaN", any implicit Nan values will result in an error being thrown. If any
  * other type is provided, an exception will be thrown.
  *
- * @param value A number or string representation of a double.
+ * @param value - A number or string representation of a double.
  * @returns The value as a number, or undefined if it's null/undefined.
  */
 export const strictParseDouble = (value: string | number): number | undefined => {
@@ -355,7 +355,7 @@ export const strictParseFloat = strictParseDouble;
  * "NaN", any implicit Nan values will result in an error being thrown. If any
  * other type is provided, an exception will be thrown.
  *
- * @param value A number or string representation of a float.
+ * @param value - A number or string representation of a float.
  * @returns The value as a number, or undefined if it's null/undefined.
  */
 export const strictParseFloat32 = (value: string | number): number | undefined => {
@@ -390,7 +390,7 @@ const parseNumber = (value: string): number => {
  * being thrown. Null or undefined will be returned as undefined. Any other
  * type will result in an exception being thrown.
  *
- * @param value A number or string representation of a non-numeric float.
+ * @param value - A number or string representation of a non-numeric float.
  * @returns The value as a number, or undefined if it's null/undefined.
  */
 export const limitedParseDouble = (value: string | number): number | undefined => {
@@ -423,7 +423,7 @@ export const limitedParseFloat = limitedParseDouble;
  * being thrown. Null or undefined will be returned as undefined. Any other
  * type will result in an exception being thrown.
  *
- * @param value A number or string representation of a non-numeric float.
+ * @param value - A number or string representation of a non-numeric float.
  * @returns The value as a number, or undefined if it's null/undefined.
  */
 export const limitedParseFloat32 = (value: string | number): number | undefined => {
@@ -455,7 +455,7 @@ const parseFloatString = (value: string): number => {
  * an integer, or the raw value is any type other than a string or number, an
  * exception will be thrown.
  *
- * @param value A number or string representation of an integer.
+ * @param value - A number or string representation of an integer.
  * @returns The value as a number, or undefined if it's null/undefined.
  */
 export const strictParseLong = (value: string | number): number | undefined => {
@@ -483,7 +483,7 @@ export const strictParseInt = strictParseLong;
  * an integer, or the raw value is any type other than a string or number, an
  * exception will be thrown.
  *
- * @param value A number or string representation of a 32-bit integer.
+ * @param value - A number or string representation of a 32-bit integer.
  * @returns The value as a number, or undefined if it's null/undefined.
  */
 export const strictParseInt32 = (value: string | number): number | undefined => {
@@ -504,7 +504,7 @@ export const strictParseInt32 = (value: string | number): number | undefined =>
  * an integer, or the raw value is any type other than a string or number, an
  * exception will be thrown.
  *
- * @param value A number or string representation of a 16-bit integer.
+ * @param value - A number or string representation of a 16-bit integer.
  * @returns The value as a number, or undefined if it's null/undefined.
  */
 export const strictParseShort = (value: string | number): number | undefined => {
@@ -525,7 +525,7 @@ export const strictParseShort = (value: string | number): number | undefined =>
  * an integer, or the raw value is any type other than a string or number, an
  * exception will be thrown.
  *
- * @param value A number or string representation of an 8-bit integer.
+ * @param value - A number or string representation of an 8-bit integer.
  * @returns The value as a number, or undefined if it's null/undefined.
  */
 export const strictParseByte = (value: string | number): number | undefined => {
@@ -551,7 +551,7 @@ const stackTraceWarning = (message: string): string => {
 };
 
 /**
- * @private
+ * @internal
  */
 export const logger = {
   warn: console.warn,

packages/smithy-client/src/ser-utils.ts

@@ -3,7 +3,7 @@
  *
  * Serializes a number, turning non-numeric values into strings.
  *
- * @param value The number to serialize.
+ * @param value - The number to serialize.
  * @returns A number, or a string if the given number was non-numeric.
  */
 export const serializeFloat = (value: number): string | number => {

packages/smithy-client/src/split-every.ts

@@ -4,9 +4,9 @@
  * Given an input string, splits based on the delimiter after a given
  * number of delimiters has been encountered.
  *
- * @param value The input string to split.
- * @param delimiter The delimiter to split on.
- * @param numDelimiters The number of delimiters to have encountered to split.
+ * @param value - The input string to split.
+ * @param delimiter - The delimiter to split on.
+ * @param numDelimiters - The number of delimiters to have encountered to split.
  */
 export function splitEvery(value: string, delimiter: string, numDelimiters: number): Array<string> {
   // Fail if we don't have a clear number to split on.

packages/types/.eslintrc.json

@@ -0,0 +1,6 @@
+{
+  "plugins": ["eslint-plugin-tsdoc"],
+  "rules": {
+    "tsdoc/syntax": "warn"
+  }
+}