ci: api-extractor support for docs

2026-03-14 10:33:30 +01:00 · 2022-06-30 15:46:14 +02:00
parent 525bf031a5
commit b2776c22d4
54 changed files with 2608 additions and 343 deletions
--- a/packages/collection/api-extractor.json
+++ b/packages/collection/api-extractor.json
@@ -0,0 +1,376 @@
+/**
+ * Config file for API Extractor.  For more info, please visit: https://api-extractor.com
+ */
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+
+	/**
+	 * Optionally specifies another JSON config file that this file extends from.  This provides a way for
+	 * standard settings to be shared across multiple projects.
+	 *
+	 * If the path starts with "./" or "../", the path is resolved relative to the folder of the file that contains
+	 * the "extends" field.  Otherwise, the first path segment is interpreted as an NPM package name, and will be
+	 * resolved using NodeJS require().
+	 *
+	 * SUPPORTED TOKENS: none
+	 * DEFAULT VALUE: ""
+	 */
+	// "extends": "./shared/api-extractor-base.json"
+	// "extends": "my-package/include/api-extractor-base.json"
+
+	/**
+	 * Determines the "<projectFolder>" token that can be used with other config file settings.  The project folder
+	 * typically contains the tsconfig.json and package.json config files, but the path is user-defined.
+	 *
+	 * The path is resolved relative to the folder of the config file that contains the setting.
+	 *
+	 * The default value for "projectFolder" is the token "<lookup>", which means the folder is determined by traversing
+	 * parent folders, starting from the folder containing api-extractor.json, and stopping at the first folder
+	 * that contains a tsconfig.json file.  If a tsconfig.json file cannot be found in this way, then an error
+	 * will be reported.
+	 *
+	 * SUPPORTED TOKENS: <lookup>
+	 * DEFAULT VALUE: "<lookup>"
+	 */
+	// "projectFolder": "..",
+
+	/**
+	 * (REQUIRED) Specifies the .d.ts file to be used as the starting point for analysis.  API Extractor
+	 * analyzes the symbols exported by this module.
+	 *
+	 * The file extension must be ".d.ts" and not ".ts".
+	 *
+	 * The path is resolved relative to the folder of the config file that contains the setting; to change this,
+	 * prepend a folder token such as "<projectFolder>".
+	 *
+	 * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
+	 */
+	"mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts",
+
+	/**
+	 * A list of NPM package names whose exports should be treated as part of this package.
+	 *
+	 * For example, suppose that Webpack is used to generate a distributed bundle for the project "library1",
+	 * and another NPM package "library2" is embedded in this bundle.  Some types from library2 may become part
+	 * of the exported API for library1, but by default API Extractor would generate a .d.ts rollup that explicitly
+	 * imports library2.  To avoid this, we can specify:
+	 *
+	 *   "bundledPackages": [ "library2" ],
+	 *
+	 * This would direct API Extractor to embed those types directly in the .d.ts rollup, as if they had been
+	 * local files for library1.
+	 */
+	"bundledPackages": [],
+
+	/**
+	 * Determines how the TypeScript compiler engine will be invoked by API Extractor.
+	 */
+	"compiler": {
+		/**
+		 * Specifies the path to the tsconfig.json file to be used by API Extractor when analyzing the project.
+		 *
+		 * The path is resolved relative to the folder of the config file that contains the setting; to change this,
+		 * prepend a folder token such as "<projectFolder>".
+		 *
+		 * Note: This setting will be ignored if "overrideTsconfig" is used.
+		 *
+		 * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
+		 * DEFAULT VALUE: "<projectFolder>/tsconfig.json"
+		 */
+		// "tsconfigFilePath": "<projectFolder>/tsconfig.json",
+		/**
+		 * Provides a compiler configuration that will be used instead of reading the tsconfig.json file from disk.
+		 * The object must conform to the TypeScript tsconfig schema:
+		 *
+		 * http://json.schemastore.org/tsconfig
+		 *
+		 * If omitted, then the tsconfig.json file will be read from the "projectFolder".
+		 *
+		 * DEFAULT VALUE: no overrideTsconfig section
+		 */
+		// "overrideTsconfig": {
+		//   . . .
+		// }
+		/**
+		 * This option causes the compiler to be invoked with the --skipLibCheck option. This option is not recommended
+		 * and may cause API Extractor to produce incomplete or incorrect declarations, but it may be required when
+		 * dependencies contain declarations that are incompatible with the TypeScript engine that API Extractor uses
+		 * for its analysis.  Where possible, the underlying issue should be fixed rather than relying on skipLibCheck.
+		 *
+		 * DEFAULT VALUE: false
+		 */
+		// "skipLibCheck": true,
+	},
+
+	/**
+	 * Configures how the API report file (*.api.md) will be generated.
+	 */
+	"apiReport": {
+		/**
+		 * (REQUIRED) Whether to generate an API report.
+		 */
+		"enabled": false
+
+		/**
+		 * The filename for the API report files.  It will be combined with "reportFolder" or "reportTempFolder" to produce
+		 * a full file path.
+		 *
+		 * The file extension should be ".api.md", and the string should not contain a path separator such as "\" or "/".
+		 *
+		 * SUPPORTED TOKENS: <packageName>, <unscopedPackageName>
+		 * DEFAULT VALUE: "<unscopedPackageName>.api.md"
+		 */
+		// "reportFileName": "<unscopedPackageName>.api.md",
+
+		/**
+		 * Specifies the folder where the API report file is written.  The file name portion is determined by
+		 * the "reportFileName" setting.
+		 *
+		 * The API report file is normally tracked by Git.  Changes to it can be used to trigger a branch policy,
+		 * e.g. for an API review.
+		 *
+		 * The path is resolved relative to the folder of the config file that contains the setting; to change this,
+		 * prepend a folder token such as "<projectFolder>".
+		 *
+		 * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
+		 * DEFAULT VALUE: "<projectFolder>/temp/"
+		 */
+		// "reportFolder": "<projectFolder>/temp/",
+
+		/**
+		 * Specifies the folder where the temporary report file is written.  The file name portion is determined by
+		 * the "reportFileName" setting.
+		 *
+		 * After the temporary file is written to disk, it is compared with the file in the "reportFolder".
+		 * If they are different, a production build will fail.
+		 *
+		 * The path is resolved relative to the folder of the config file that contains the setting; to change this,
+		 * prepend a folder token such as "<projectFolder>".
+		 *
+		 * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
+		 * DEFAULT VALUE: "<projectFolder>/temp/"
+		 */
+		// "reportTempFolder": "<projectFolder>/temp/"
+	},
+
+	/**
+	 * Configures how the doc model file (*.api.json) will be generated.
+	 */
+	"docModel": {
+		/**
+		 * (REQUIRED) Whether to generate a doc model file.
+		 */
+		"enabled": true,
+
+		/**
+		 * The output path for the doc model file.  The file extension should be ".api.json".
+		 *
+		 * The path is resolved relative to the folder of the config file that contains the setting; to change this,
+		 * prepend a folder token such as "<projectFolder>".
+		 *
+		 * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
+		 * DEFAULT VALUE: "<projectFolder>/temp/<unscopedPackageName>.api.json"
+		 */
+		"apiJsonFilePath": "<projectFolder>/docs/docs.api.json"
+	},
+
+	/**
+	 * Configures how the .d.ts rollup file will be generated.
+	 */
+	"dtsRollup": {
+		/**
+		 * (REQUIRED) Whether to generate the .d.ts rollup file.
+		 */
+		"enabled": false
+
+		/**
+		 * Specifies the output path for a .d.ts rollup file to be generated without any trimming.
+		 * This file will include all declarations that are exported by the main entry point.
+		 *
+		 * If the path is an empty string, then this file will not be written.
+		 *
+		 * The path is resolved relative to the folder of the config file that contains the setting; to change this,
+		 * prepend a folder token such as "<projectFolder>".
+		 *
+		 * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
+		 * DEFAULT VALUE: "<projectFolder>/dist/<unscopedPackageName>.d.ts"
+		 */
+		// "untrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>.d.ts",
+
+		/**
+		 * Specifies the output path for a .d.ts rollup file to be generated with trimming for an "alpha" release.
+		 * This file will include only declarations that are marked as "@public", "@beta", or "@alpha".
+		 *
+		 * The path is resolved relative to the folder of the config file that contains the setting; to change this,
+		 * prepend a folder token such as "<projectFolder>".
+		 *
+		 * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
+		 * DEFAULT VALUE: ""
+		 */
+		// "alphaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-alpha.d.ts",
+
+		/**
+		 * Specifies the output path for a .d.ts rollup file to be generated with trimming for a "beta" release.
+		 * This file will include only declarations that are marked as "@public" or "@beta".
+		 *
+		 * The path is resolved relative to the folder of the config file that contains the setting; to change this,
+		 * prepend a folder token such as "<projectFolder>".
+		 *
+		 * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
+		 * DEFAULT VALUE: ""
+		 */
+		// "betaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-beta.d.ts",
+
+		/**
+		 * Specifies the output path for a .d.ts rollup file to be generated with trimming for a "public" release.
+		 * This file will include only declarations that are marked as "@public".
+		 *
+		 * If the path is an empty string, then this file will not be written.
+		 *
+		 * The path is resolved relative to the folder of the config file that contains the setting; to change this,
+		 * prepend a folder token such as "<projectFolder>".
+		 *
+		 * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
+		 * DEFAULT VALUE: ""
+		 */
+		// "publicTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-public.d.ts",
+
+		/**
+		 * When a declaration is trimmed, by default it will be replaced by a code comment such as
+		 * "Excluded from this release type: exampleMember".  Set "omitTrimmingComments" to true to remove the
+		 * declaration completely.
+		 *
+		 * DEFAULT VALUE: false
+		 */
+		// "omitTrimmingComments": true
+	},
+
+	/**
+	 * Configures how the tsdoc-metadata.json file will be generated.
+	 */
+	"tsdocMetadata": {
+		/**
+		 * Whether to generate the tsdoc-metadata.json file.
+		 *
+		 * DEFAULT VALUE: true
+		 */
+		// "enabled": true,
+		/**
+		 * Specifies where the TSDoc metadata file should be written.
+		 *
+		 * The path is resolved relative to the folder of the config file that contains the setting; to change this,
+		 * prepend a folder token such as "<projectFolder>".
+		 *
+		 * The default value is "<lookup>", which causes the path to be automatically inferred from the "tsdocMetadata",
+		 * "typings" or "main" fields of the project's package.json.  If none of these fields are set, the lookup
+		 * falls back to "tsdoc-metadata.json" in the package folder.
+		 *
+		 * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
+		 * DEFAULT VALUE: "<lookup>"
+		 */
+		// "tsdocMetadataFilePath": "<projectFolder>/dist/tsdoc-metadata.json"
+	},
+
+	/**
+	 * Specifies what type of newlines API Extractor should use when writing output files.  By default, the output files
+	 * will be written with Windows-style newlines.  To use POSIX-style newlines, specify "lf" instead.
+	 * To use the OS's default newline kind, specify "os".
+	 *
+	 * DEFAULT VALUE: "crlf"
+	 */
+	"newlineKind": "lf",
+
+	/**
+	 * Configures how API Extractor reports error and warning messages produced during analysis.
+	 *
+	 * There are three sources of messages:  compiler messages, API Extractor messages, and TSDoc messages.
+	 */
+	"messages": {
+		/**
+		 * Configures handling of diagnostic messages reported by the TypeScript compiler engine while analyzing
+		 * the input .d.ts files.
+		 *
+		 * TypeScript message identifiers start with "TS" followed by an integer.  For example: "TS2551"
+		 *
+		 * DEFAULT VALUE:  A single "default" entry with logLevel=warning.
+		 */
+		"compilerMessageReporting": {
+			/**
+			 * Configures the default routing for messages that don't match an explicit rule in this table.
+			 */
+			"default": {
+				/**
+				 * Specifies whether the message should be written to the the tool's output log.  Note that
+				 * the "addToApiReportFile" property may supersede this option.
+				 *
+				 * Possible values: "error", "warning", "none"
+				 *
+				 * Errors cause the build to fail and return a nonzero exit code.  Warnings cause a production build fail
+				 * and return a nonzero exit code.  For a non-production build (e.g. when "api-extractor run" includes
+				 * the "--local" option), the warning is displayed but the build will not fail.
+				 *
+				 * DEFAULT VALUE: "warning"
+				 */
+				"logLevel": "warning"
+
+				/**
+				 * When addToApiReportFile is true:  If API Extractor is configured to write an API report file (.api.md),
+				 * then the message will be written inside that file; otherwise, the message is instead logged according to
+				 * the "logLevel" option.
+				 *
+				 * DEFAULT VALUE: false
+				 */
+				// "addToApiReportFile": false
+			}
+
+			// "TS2551": {
+			//   "logLevel": "warning",
+			//   "addToApiReportFile": true
+			// },
+			//
+			// . . .
+		},
+
+		/**
+		 * Configures handling of messages reported by API Extractor during its analysis.
+		 *
+		 * API Extractor message identifiers start with "ae-".  For example: "ae-extra-release-tag"
+		 *
+		 * DEFAULT VALUE: See api-extractor-defaults.json for the complete table of extractorMessageReporting mappings
+		 */
+		"extractorMessageReporting": {
+			"default": {
+				"logLevel": "warning"
+				// "addToApiReportFile": false
+			}
+
+			// "ae-extra-release-tag": {
+			//   "logLevel": "warning",
+			//   "addToApiReportFile": true
+			// },
+			//
+			// . . .
+		},
+
+		/**
+		 * Configures handling of messages reported by the TSDoc parser when analyzing code comments.
+		 *
+		 * TSDoc message identifiers start with "tsdoc-".  For example: "tsdoc-link-tag-unescaped-text"
+		 *
+		 * DEFAULT VALUE:  A single "default" entry with logLevel=warning.
+		 */
+		"tsdocMessageReporting": {
+			"default": {
+				"logLevel": "warning"
+				// "addToApiReportFile": false
+			}
+
+			// "tsdoc-link-tag-unescaped-text": {
+			//   "logLevel": "warning",
+			//   "addToApiReportFile": true
+			// },
+			//
+			// . . .
+		}
+	}
+}
--- a/packages/collection/package.json
+++ b/packages/collection/package.json
@@ -6,7 +6,7 @@
 		"build": "tsup",
 		"lint": "prettier --cache --check . && eslint src __tests__ --ext mjs,js,ts --cache",
 		"format": "prettier --cache --write . && eslint src __tests__ --ext mjs,js,ts --fix --cache",
-		"docs": "docgen -i src/index.ts -c docs/index.json -o docs/docs.json --typescript",
+		"docs": "docgen -i src/index.ts -c docs/index.json -o docs/docs.json --typescript && api-extractor run --local",
 		"prepack": "yarn build && yarn lint",
 		"changelog": "git cliff --prepend ./CHANGELOG.md -u -c ./cliff.toml -r ../../ --include-path 'packages/collection/*'",
 		"release": "cliff-jumper"
@@ -51,6 +51,7 @@
 		"@discordjs/docgen": "workspace:^",
 		"@discordjs/scripts": "workspace:^",
 		"@favware/cliff-jumper": "^1.8.3",
+		"@microsoft/api-extractor": "^7.28.2",
 		"@types/node": "^18.0.0",
 		"eslint": "^8.18.0",
 		"prettier": "^2.7.1",
--- a/packages/collection/src/index.ts
+++ b/packages/collection/src/index.ts
@@ -33,8 +33,8 @@ export class Collection<K, V> extends Map<K, V> {
 	/**
 	 * Obtains the value of the given key if it exists, otherwise sets and returns the value provided by the default value generator.
 	 *
-	 * @param key The key to get if it exists, or set otherwise
-	 * @param defaultValueGenerator A function that generates the default value
+	 * @param key - The key to get if it exists, or set otherwise
+	 * @param defaultValueGenerator - A function that generates the default value
 	 *
 	 * @example
 	 * collection.ensure(guildId, () => defaultGuildConfig);
@@ -72,7 +72,7 @@ export class Collection<K, V> extends Map<K, V> {
 	/**
 	 * Obtains the first value(s) in this collection.
 	 *
-	 * @param amount Amount of values to obtain from the beginning
+	 * @param amount - Amount of values to obtain from the beginning
 	 *
 	 * @returns A single value if no amount is provided or an array of values, starting from the end if amount is negative
 	 */
@@ -91,7 +91,7 @@ export class Collection<K, V> extends Map<K, V> {
 	/**
 	 * Obtains the first key(s) in this collection.
 	 *
-	 * @param amount Amount of keys to obtain from the beginning
+	 * @param amount - Amount of keys to obtain from the beginning
 	 *
 	 * @returns A single key if no amount is provided or an array of keys, starting from the end if
 	 * amount is negative
@@ -111,7 +111,7 @@ export class Collection<K, V> extends Map<K, V> {
 	/**
 	 * Obtains the last value(s) in this collection.
 	 *
-	 * @param amount Amount of values to obtain from the end
+	 * @param amount - Amount of values to obtain from the end
 	 *
 	 * @returns A single value if no amount is provided or an array of values, starting from the start if
 	 * amount is negative
@@ -129,7 +129,7 @@ export class Collection<K, V> extends Map<K, V> {
 	/**
 	 * Obtains the last key(s) in this collection.
 	 *
-	 * @param amount Amount of keys to obtain from the end
+	 * @param amount - Amount of keys to obtain from the end
 	 *
 	 * @returns A single key if no amount is provided or an array of keys, starting from the start if
 	 * amount is negative
@@ -149,7 +149,7 @@ export class Collection<K, V> extends Map<K, V> {
 	 * Returns the item at a given index, allowing for positive and negative integers.
 	 * Negative integers count back from the last item in the collection.
 	 *
-	 * @param index The index of the element to obtain
+	 * @param index - The index of the element to obtain
 	 */
 	public at(index: number) {
 		index = Math.floor(index);
@@ -162,7 +162,7 @@ export class Collection<K, V> extends Map<K, V> {
 	 * Returns the key at a given index, allowing for positive and negative integers.
 	 * Negative integers count back from the last item in the collection.
 	 *
-	 * @param index The index of the key to obtain
+	 * @param index - The index of the key to obtain
 	 */
 	public keyAt(index: number) {
 		index = Math.floor(index);
@@ -173,7 +173,7 @@ export class Collection<K, V> extends Map<K, V> {
 	/**
 	 * Obtains unique random value(s) from this collection.
 	 *
-	 * @param amount Amount of values to obtain randomly
+	 * @param amount - Amount of values to obtain randomly
 	 *
 	 * @returns A single value if no amount is provided or an array of values
 	 */
@@ -192,7 +192,7 @@ export class Collection<K, V> extends Map<K, V> {
 	/**
 	 * Obtains unique random key(s) from this collection.
 	 *
-	 * @param amount Amount of keys to obtain randomly
+	 * @param amount - Amount of keys to obtain randomly
 	 *
 	 * @returns A single key if no amount is provided or an array
 	 */
@@ -226,8 +226,8 @@ export class Collection<K, V> extends Map<K, V> {
 	 * should use the `get` method. See
 	 * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/get) for details.</warn>
 	 *
-	 * @param fn The function to test with (should return boolean)
-	 * @param thisArg Value to use as `this` when executing function
+	 * @param fn - The function to test with (should return boolean)
+	 * @param thisArg - Value to use as `this` when executing function
 	 *
 	 * @example
 	 * collection.find(user => user.username === 'Bob');
@@ -253,8 +253,8 @@ export class Collection<K, V> extends Map<K, V> {
 	 * [Array.findIndex()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex),
 	 * but returns the key rather than the positional index.
 	 *
-	 * @param fn The function to test with (should return boolean)
-	 * @param thisArg Value to use as `this` when executing function
+	 * @param fn - The function to test with (should return boolean)
+	 * @param thisArg - Value to use as `this` when executing function
 	 *
 	 * @example
 	 * collection.findKey(user => user.username === 'Bob');
@@ -278,8 +278,8 @@ export class Collection<K, V> extends Map<K, V> {
 	/**
 	 * Removes items that satisfy the provided filter function.
 	 *
-	 * @param fn Function used to test (should return a boolean)
-	 * @param thisArg Value to use as `this` when executing function
+	 * @param fn - Function used to test (should return a boolean)
+	 * @param thisArg - Value to use as `this` when executing function
 	 *
 	 * @returns The number of removed entries
 	 */
@@ -300,8 +300,8 @@ export class Collection<K, V> extends Map<K, V> {
 	 * [Array.filter()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter),
 	 * but returns a Collection instead of an Array.
 	 *
-	 * @param fn The function to test with (should return boolean)
-	 * @param thisArg Value to use as `this` when executing function
+	 * @param fn - The function to test with (should return boolean)
+	 * @param thisArg - Value to use as `this` when executing function
 	 *
 	 * @example
 	 * collection.filter(user => user.username === 'Bob');
@@ -332,8 +332,8 @@ export class Collection<K, V> extends Map<K, V> {
 	 * Partitions the collection into two collections where the first collection
 	 * contains the items that passed and the second contains the items that failed.
 	 *
-	 * @param fn Function used to test (should return a boolean)
-	 * @param thisArg Value to use as `this` when executing function
+	 * @param fn - Function used to test (should return a boolean)
+	 * @param thisArg - Value to use as `this` when executing function
 	 *
 	 * @example
 	 * const [big, small] = collection.partition(guild => guild.memberCount > 250);
@@ -381,8 +381,8 @@ export class Collection<K, V> extends Map<K, V> {
 	 * Maps each item into a Collection, then joins the results into a single Collection. Identical in behavior to
 	 * [Array.flatMap()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flatMap).
 	 *
-	 * @param fn Function that produces a new Collection
-	 * @param thisArg Value to use as `this` when executing function
+	 * @param fn - Function that produces a new Collection
+	 * @param thisArg - Value to use as `this` when executing function
 	 *
 	 * @example
 	 * collection.flatMap(guild => guild.members.cache);
@@ -401,8 +401,8 @@ export class Collection<K, V> extends Map<K, V> {
 	 * Maps each item to another value into an array. Identical in behavior to
 	 * [Array.map()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map).
 	 *
-	 * @param fn Function that produces an element of the new array, taking three arguments
-	 * @param thisArg Value to use as `this` when executing function
+	 * @param fn - Function that produces an element of the new array, taking three arguments
+	 * @param thisArg - Value to use as `this` when executing function
 	 *
 	 * @example
 	 * collection.map(user => user.tag);
@@ -425,8 +425,8 @@ export class Collection<K, V> extends Map<K, V> {
 	 * Maps each item to another value into a collection. Identical in behavior to
 	 * [Array.map()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map).
 	 *
-	 * @param fn Function that produces an element of the new collection, taking three arguments
-	 * @param thisArg Value to use as `this` when executing function
+	 * @param fn - Function that produces an element of the new collection, taking three arguments
+	 * @param thisArg - Value to use as `this` when executing function
 	 *
 	 * @example
 	 * collection.mapValues(user => user.tag);
@@ -445,8 +445,8 @@ export class Collection<K, V> extends Map<K, V> {
 	 * Checks if there exists an item that passes a test. Identical in behavior to
 	 * [Array.some()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some).
 	 *
-	 * @param fn Function used to test (should return a boolean)
-	 * @param thisArg Value to use as `this` when executing function
+	 * @param fn - Function used to test (should return a boolean)
+	 * @param thisArg - Value to use as `this` when executing function
 	 *
 	 * @example
 	 * collection.some(user => user.discriminator === '0000');
@@ -466,8 +466,8 @@ export class Collection<K, V> extends Map<K, V> {
 	 * Checks if all items passes a test. Identical in behavior to
 	 * [Array.every()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every).
 	 *
-	 * @param fn Function used to test (should return a boolean)
-	 * @param thisArg Value to use as `this` when executing function
+	 * @param fn - Function used to test (should return a boolean)
+	 * @param thisArg - Value to use as `this` when executing function
 	 *
 	 * @example
 	 * collection.every(user => !user.bot);
@@ -497,9 +497,9 @@ export class Collection<K, V> extends Map<K, V> {
 	 * Applies a function to produce a single value. Identical in behavior to
 	 * [Array.reduce()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce).
 	 *
-	 * @param fn Function used to reduce, taking four arguments; `accumulator`, `currentValue`, `currentKey`,
+	 * @param fn - Function used to reduce, taking four arguments; `accumulator`, `currentValue`, `currentKey`,
 	 * and `collection`
-	 * @param initialValue Starting value for the accumulator
+	 * @param initialValue - Starting value for the accumulator
 	 *
 	 * @example
 	 * collection.reduce((acc, guild) => acc + guild.memberCount, 0);
@@ -536,8 +536,8 @@ export class Collection<K, V> extends Map<K, V> {
 	 * [Map.forEach()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/forEach),
 	 * but returns the collection instead of undefined.
 	 *
-	 * @param fn Function to execute for each element
-	 * @param thisArg Value to use as `this` when executing function
+	 * @param fn - Function to execute for each element
+	 * @param thisArg - Value to use as `this` when executing function
 	 *
 	 * @example
 	 * collection
@@ -556,8 +556,8 @@ export class Collection<K, V> extends Map<K, V> {
 	/**
 	 * Runs a function on the collection and returns the collection.
 	 *
-	 * @param fn Function to execute
-	 * @param thisArg Value to use as `this` when executing function
+	 * @param fn - Function to execute
+	 * @param thisArg - Value to use as `this` when executing function
 	 *
 	 * @example
 	 * collection
@@ -587,7 +587,7 @@ export class Collection<K, V> extends Map<K, V> {
 	/**
 	 * Combines this collection with others into a new collection. None of the source collections are modified.
 	 *
-	 * @param collections Collections to merge
+	 * @param collections - Collections to merge
 	 *
 	 * @example
 	 * const newColl = someColl.concat(someOtherColl, anotherColl, ohBoyAColl);
@@ -605,7 +605,7 @@ export class Collection<K, V> extends Map<K, V> {
 	 * This is different to checking for equality using equal-signs, because
 	 * the collections may be different objects, but contain the same data.
 	 *
-	 * @param collection Collection to compare with
+	 * @param collection - Collection to compare with
 	 *
 	 * @returns Whether the collections have identical contents
 	 */
@@ -627,7 +627,7 @@ export class Collection<K, V> extends Map<K, V> {
 	 * The sort is not necessarily stable in Node 10 or older.
 	 * The default sort order is according to string Unicode code points.
 	 *
-	 * @param compareFunction Specifies a function that defines the sort order.
+	 * @param compareFunction - Specifies a function that defines the sort order.
 	 * If omitted, the collection is sorted according to each character's Unicode code point value, according to the string conversion of each element.
 	 *
 	 * @example
@@ -650,7 +650,7 @@ export class Collection<K, V> extends Map<K, V> {
 	/**
 	 * The intersect method returns a new structure containing items where the keys and values are present in both original structures.
 	 *
-	 * @param other The other Collection to filter against
+	 * @param other - The other Collection to filter against
 	 */
 	public intersect<T>(other: ReadonlyCollection<K, T>): Collection<K, T> {
 		const coll = new this.constructor[Symbol.species]<K, T>();
@@ -665,7 +665,7 @@ export class Collection<K, V> extends Map<K, V> {
 	/**
 	 * The difference method returns a new structure containing items where the key is present in one of the original structures but not the other.
 	 *
-	 * @param other The other Collection to filter against
+	 * @param other - The other Collection to filter against
 	 */
 	public difference<T>(other: ReadonlyCollection<K, T>): Collection<K, V | T> {
 		const coll = new this.constructor[Symbol.species]<K, V | T>();
@@ -680,10 +680,10 @@ export class Collection<K, V> extends Map<K, V> {

 	/**
 	 * Merges two Collections together into a new Collection.
-	 * @param other The other Collection to merge with
-	 * @param whenInSelf Function getting the result if the entry only exists in this Collection
-	 * @param whenInOther Function getting the result if the entry only exists in the other Collection
-	 * @param whenInBoth Function getting the result if the entry exists in both Collections
+	 * @param other - The other Collection to merge with
+	 * @param whenInSelf - Function getting the result if the entry only exists in this Collection
+	 * @param whenInOther - Function getting the result if the entry only exists in the other Collection
+	 * @param whenInBoth - Function getting the result if the entry exists in both Collections
 	 *
 	 * @example
 	 * // Sums up the entries in two collections.
@@ -734,7 +734,7 @@ export class Collection<K, V> extends Map<K, V> {
 	 * The sort is not necessarily stable in Node 10 or older.
 	 * The default sort order is according to string Unicode code points.
 	 *
-	 * @param compareFunction Specifies a function that defines the sort order.
+	 * @param compareFunction - Specifies a function that defines the sort order.
 	 * If omitted, the collection is sorted according to each character's Unicode code point value,
 	 * according to the string conversion of each element.
 	 *
@@ -756,8 +756,9 @@ export class Collection<K, V> extends Map<K, V> {

 	/**
 	 * Creates a Collection from a list of entries.
-	 * @param entries The list of entries
-	 * @param combine Function to combine an existing entry with a new one
+	 *
+	 * @param entries - The list of entries
+	 * @param combine - Function to combine an existing entry with a new one
 	 *
 	 * @example
 	 * Collection.combineEntries([["a", 1], ["b", 2], ["a", 2]], (x, y) => x + y);