AngularJS中ESLint与ngDoc名称不兼容问题求助

I've run into this exact issue when working with ngDoc and ESLint too—frustrating to lose the useful parameter checking just because ngDoc uses colon-separated names like myModule.controller:myController. Here's how to fix it without disabling the rule entirely:

The Root Cause #

ESLint's valid-jsdoc rule uses a default regex pattern to validate JSDoc names, and that pattern doesn't include colons. Since ngDoc uses colons to namespace components (modules, controllers, directives, etc.), the rule flags these as invalid names incorrectly.

The Solution: Customize the matchName Regex #

You can tweak the valid-jsdoc rule's configuration to allow colons in names while keeping all the useful checks (like ensuring parameters are documented). Here's how to update your ESLint config:

1. Open your ESLint configuration file (usually .eslintrc.js or .eslintrc.json).
2. Modify the valid-jsdoc rule to include a custom matchName regex that accepts colons.

Example .eslintrc.js configuration:

module.exports = {
  // ... other ESLint settings
  rules: {
    'valid-jsdoc': [
      'error',
      {
        // Keep the checks you care about
        requireParamDescription: true,
        requireReturnDescription: true,
        requireReturnType: false, // Adjust based on your needs
        // Allow names with letters, numbers, underscores, dots, and colons
        matchName: /^[\w:.]+$/
      }
    ]
  }
};

Breakdown of the Regex #

The regex ^[\w:.]+$ matches:

• \w: Any alphanumeric character or underscore
• .: Dot (for nested modules like myModule.subModule)
• :: Colon (for ngDoc's component naming like controller:myController)
• +: Ensures there's at least one character in the name

If you want to be more strict (only allowing colon-separated names in the ngDoc pattern, e.g., moduleName.component:componentName), you can use a more specific regex like:

/^[\w.]+\:\w+$/

This way, you keep all the value of valid-jsdoc (catching undocumented parameters, missing return descriptions, etc.) while letting ngDoc's naming convention pass without errors.

内容的提问来源于stack exchange，提问作者Luis Gonzalez