docs(linter): clarify jsdoc/check-tag-names configuration (#11394)

Ragnar-Oock · graphite-app[bot] · camc314 · web-flow · commit eae51ca2a780 · 2025-05-30T14:04:16.000+01:00
Explain how custom tags can be registered to avoid false positives when using them in comments. related issue #11392 --------- Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com> Co-authored-by: Cameron <cameron.clark@hey.com> Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
diff --git a/crates/oxc_linter/src/rules/jsdoc/check_tag_names.rs b/crates/oxc_linter/src/rules/jsdoc/check_tag_names.rs
@@ -43,6 +43,40 @@ declare_oxc_lint!(
     /// ```javascript
     /// /** @param */
     /// ```
+    ///
+    /// ### Options
+    ///
+    /// Configuration for allowed tags is done via [`settings.jsdoc.tagNamePreference`](/docs/guide/usage/linter/config-file-reference.html#settings-jsdoc-tagnamepreference).
+    /// There is no CLI-only parameter for this rule.
+    ///
+    /// You can add custom tags by adding a key-value pair where both match the name of the tag you want to add, like so:
+    ///
+    /// ::: code-group
+    ///
+    /// ```json [Config (.oxlintrc.json)]
+    /// {
+    ///   "plugins": ["jsdoc"],
+    ///   "rules": {
+    ///     "jsdoc/check-tag-names": "error"
+    ///   },
+    ///   "settings": { // [!code highlight:7]
+    ///     "jsdoc": {
+    ///       "tagNamePreference": {
+    ///         "customTagName": "customTagName"
+    ///       }
+    ///     }
+    ///   }
+    /// }
+    /// ```
+    /// :::
+    ///
+    /// Examples of correct code for this rule with the above configuration, adding the `customTagName` tag:
+    ///
+    /// ```js
+    /// /**
+    ///  * @customTagName
+    ///  */
+    /// ```
     CheckTagNames,
     jsdoc,
     correctness
