refactor: update and fix error types in JSDoc comments (#213)

Author: lumirlumir

packages/config-array/src/config-array.js

@@ -555,7 +555,7 @@ function assertNormalized(configArray) {
  * Ensures that config types are valid.
  * @param {Array<string>} extraConfigTypes The config types to check.
  * @returns {void}
- * @throws {Error} When the config types array is invalid.
+ * @throws {TypeError} When the config types array is invalid.
  */
 function assertExtraConfigTypes(extraConfigTypes) {
 	if (extraConfigTypes.length > 2) {
@@ -577,7 +577,7 @@ function assertExtraConfigTypes(extraConfigTypes) {
  * Returns path-handling implementations for Unix or Windows, depending on a given absolute path.
  * @param {string} fileOrDirPath The absolute path to check.
  * @returns {PathImpl} Path-handling implementations for the specified path.
- * @throws An error is thrown if the specified argument is not an absolute path.
+ * @throws {Error} An error is thrown if the specified argument is not an absolute path.
  */
 function getPathImpl(fileOrDirPath) {
 	// Posix absolute paths always start with a slash.
@@ -655,6 +655,7 @@ export class ConfigArray extends Array {
 	 * @param {Object} [options.schema] The additional schema
 	 *      definitions to use for the ConfigArray schema.
 	 * @param {Array<string>} [options.extraConfigTypes] List of config types supported.
+	 * @throws {TypeError} When the `basePath` is not a non-empty string,
 	 */
 	constructor(
 		configs,

packages/config-helpers/src/define-config.js

@@ -204,6 +204,7 @@ function normalizePluginConfig(userNamespace, plugin, config) {
  * @param {Config|LegacyConfig|(Config|LegacyConfig)[]} pluginConfig The plugin config to normalize.
  * @param {string} pluginConfigName The name of the plugin config.
  * @return {InfiniteConfigArray} The normalized plugin config.
+ * @throws {TypeError} If the plugin config is a legacy config.
  */
 function deepNormalizePluginConfig(
 	userPluginNamespace,
@@ -238,6 +239,7 @@ function deepNormalizePluginConfig(
  * @param {Config} config The config object.
  * @param {string} pluginConfigName The name of the plugin config.
  * @return {InfiniteConfigArray} The plugin config.
+ * @throws {TypeError} If the plugin config is not found or is a legacy config.
  */
 function findPluginConfig(config, pluginConfigName) {
 	const { namespace: userPluginNamespace, name: configName } =
@@ -386,6 +388,7 @@ function extendConfig(baseConfig, baseConfigName, extension, extensionName) {
  * @param {ConfigWithExtends} config The config object.
  * @param {WeakMap<Config, string>} configNames The map of config objects to their names.
  * @return {Config[]} The flattened list of config objects.
+ * @throws {TypeError} If the `extends` property is not an array or if nested `extends` is found.
  */
 function processExtends(config, configNames) {
 	if (!config.extends) {
@@ -490,6 +493,7 @@ function processConfigList(configList, configNames) {
  * Helper function to define a config array.
  * @param {ConfigWithExtendsArray} args The arguments to the function.
  * @returns {Config[]} The config array.
+ * @throws {TypeError} If no arguments are provided or if an argument is not an object.
  */
 export function defineConfig(...args) {
 	const configNames = new WeakMap();

packages/config-helpers/src/global-ignores.js

@@ -24,6 +24,7 @@ let globalIgnoreCount = 0;
  * @param {string[]} ignorePatterns The ignore patterns.
  * @param {string} [name] The name of the global ignores config.
  * @returns {Config} The global ignores config.
+ * @throws {TypeError} If ignorePatterns is not an array or if it is empty.
  */
 export function globalIgnores(ignorePatterns, name) {
 	if (!Array.isArray(ignorePatterns)) {

packages/object-schema/src/object-schema.js

@@ -25,9 +25,9 @@ import { ValidationStrategy } from "./validation-strategy.js";
  * @param {string} name The name of the key this strategy is for.
  * @param {PropertyDefinition} definition The strategy for the object key.
  * @returns {void}
- * @throws {Error} When the strategy is missing a name.
- * @throws {Error} When the strategy is missing a merge() method.
- * @throws {Error} When the strategy is missing a validate() method.
+ * @throws {TypeError} When the strategy is missing a name.
+ * @throws {TypeError} When the strategy is missing a merge() method.
+ * @throws {TypeError} When the strategy is missing a validate() method.
  */
 function validateDefinition(name, definition) {
 	let hasSchema = false;
@@ -152,6 +152,7 @@ export class ObjectSchema {
 	/**
 	 * Creates a new instance.
 	 * @param {ObjectDefinition} definitions The schema definitions.
+	 * @throws {Error} When the definitions are missing or invalid.
 	 */
 	constructor(definitions) {
 		if (!definitions) {
@@ -221,7 +222,7 @@ export class ObjectSchema {
 	 * strategy.
 	 * @param {...Object} objects The objects to merge.
 	 * @returns {Object} A new object with a mix of all objects' keys.
-	 * @throws {Error} If any object is invalid.
+	 * @throws {TypeError} If any object is invalid.
 	 */
 	merge(...objects) {
 		// double check arguments

packages/plugin-kit/src/source-code.js

@@ -255,6 +255,7 @@ export class TextSourceCodeBase {
 	 * Returns the loc information for the given node or token.
 	 * @param {Options['SyntaxElementWithLoc']} nodeOrToken The node or token to get the loc information for.
 	 * @returns {SourceLocation} The loc information for the node or token.
+	 * @throws {Error} If the node or token does not have loc information.
 	 */
 	getLoc(nodeOrToken) {
 		if (hasESTreeStyleLoc(nodeOrToken)) {
@@ -274,6 +275,7 @@ export class TextSourceCodeBase {
 	 * Returns the range information for the given node or token.
 	 * @param {Options['SyntaxElementWithLoc']} nodeOrToken The node or token to get the range information for.
 	 * @returns {SourceRange} The range information for the node or token.
+	 * @throws {Error} If the node or token does not have range information.
 	 */
 	getRange(nodeOrToken) {
 		if (hasESTreeStyleRange(nodeOrToken)) {
@@ -297,6 +299,7 @@ export class TextSourceCodeBase {
 	 * Returns the parent of the given node.
 	 * @param {Options['SyntaxElementWithLoc']} node The node to get the parent of.
 	 * @returns {Options['SyntaxElementWithLoc']|undefined} The parent of the node.
+	 * @throws {Error} If the method is not implemented in the subclass.
 	 */
 	getParent(node) {
 		throw new Error("Not implemented.");