eslint-plugin-tsdoc-require-2 1.0.6 → 1.0.8

package/docs/rules/required-tags/require-type-param.md

@@ -1,29 +1,45 @@
 # tsdoc-require-2/require-type-param
 
-Require the `@typeParam` tag in TSDoc blocks for exported declarations.
+Require the `@typeParam` tag in TSDoc blocks for targeted declarations.
 
 ## Rule details
 
-By default, this rule reports exported declarations (and supported default exports) that have TSDoc but are missing `@typeParam`. Set `includeNonExported: true` to also check non-exported top-level declarations.
+This rule reports declarations that already have TSDoc but are missing `@typeParam`.
 
-It supports the same options as [`tsdoc-require-2/require`](../require.md):
+It does not create a TSDoc block. Pair it with [`tsdoc-require-2/require`](../require.md) when you also want to require comments.
 
-- `enforceFor`: choose which declaration kinds are checked.
-- `includeNonExported`: when `true`, also check non-exported top-level declarations (default: `false`).
+## Why use it
+
+`@typeParam` makes generic contracts easier to understand for callers and maintainers.
 
 ## Options
 
-```json
-{
-  "rules": {
-    "tsdoc-require-2/require-type-param": [
-      "error",
-      {
-        "enforceFor": ["class", "function", "interface", "type", "enum", "variable", "object"]
-      }
-    ]
-  }
-}
+This rule supports the same options as [`tsdoc-require-2/require`](../require.md):
+
+- `enforceFor`
+- `exportMode`
+- `includeNonExported` (legacy alias for `exportMode: "all"`)
+
+Flat config example (generic declarations only):
+
+```ts
+import tsdocRequire from "eslint-plugin-tsdoc-require-2";
+
+export default [
+  {
+    plugins: {
+      "tsdoc-require-2": tsdocRequire,
+    },
+    rules: {
+      "tsdoc-require-2/require-type-param": [
+        "error",
+        {
+          enforceFor: ["class", "function", "interface", "type"],
+        },
+      ],
+    },
+  },
+];
 ```
 
 ## Examples
@@ -32,10 +48,10 @@ It supports the same options as [`tsdoc-require-2/require`](../require.md):
 
 ```ts
 /**
- * Performs a task.
+ * Wraps data in a typed container.
  */
-export function runTask(value: string): string {
-  return value;
+export function wrap<T>(value: T): { value: T } {
+  return { value };
 }
 ```
 
@@ -43,15 +59,19 @@ export function runTask(value: string): string {
 
 ```ts
 /**
- * Performs a task.
- * @typeParam
+ * Wraps data in a typed container.
+ * @typeParam T - Value type stored in the wrapper.
  */
-export function runTask(value: string): string {
-  return value;
+export function wrap<T>(value: T): { value: T } {
+  return { value };
 }
 ```
 
+## Behavior notes
+
+This rule checks tag presence. It does not verify one `@typeParam` tag per generic parameter.
+
 ## Further reading
 
-- TSDoc tag reference: <https://tsdoc.org/pages/tags/typeparam/>
-- Rule index: [required-tags](../required-tags.md)
+- [TSDoc tag reference: @typeParam](https://tsdoc.org/pages/tags/typeparam/)
+- [required-tags family overview](../required-tags.md)

package/docs/rules/required-tags/require-use-declared-type.md

@@ -0,0 +1,87 @@
+# tsdoc-require-2/require-use-declared-type
+
+Require the `@useDeclaredType` tag in TSDoc blocks for supported TypeScript declarations.
+
+## Rule Details
+
+This rule reports supported declarations and default exports when a TSDoc block exists but does not contain `@useDeclaredType`. It does not create the TSDoc block itself, so pair it with [`tsdoc-require-2/require`](../require.md) when you also want to require the comment.
+
+## Options
+
+This rule accepts the same options as [`tsdoc-require-2/require`](../require.md):
+
+- `enforceFor`: limit which declaration kinds are checked.
+- `exportMode`: choose whether to check exported declarations, non-exported top-level declarations, or both.
+- `includeNonExported`: legacy alias for `exportMode: "all"`.
+
+  ```ts
+  type Options = [
+      {
+          enforceFor?: Array<
+              | "class"
+              | "enum"
+              | "function"
+              | "interface"
+              | "namespace"
+              | "object"
+              | "type"
+              | "variable"
+          >;
+          exportMode?: "all" | "exported" | "non-exported";
+          includeNonExported?: boolean;
+      },
+  ];
+  ```
+
+  Default options:
+
+  ```ts
+  [
+      {
+          enforceFor: [
+              "class",
+              "enum",
+              "function",
+              "interface",
+              "namespace",
+              "object",
+              "type",
+              "variable",
+          ],
+          exportMode: "exported",
+      },
+  ]
+  ```
+
+## ❌ Incorrect
+
+```ts
+/**
+ * Performs a tagged operation.
+ */
+export function taggedFunction(value: string): string {
+    return value;
+}
+```
+
+## ✅ Correct
+
+```ts
+/**
+ * Performs a tagged operation.
+ * @useDeclaredType
+ */
+export function taggedFunction(value: string): string {
+    return value;
+}
+```
+
+## When Not To Use It
+
+Disable this rule if your documentation convention does not require `@useDeclaredType` on the declarations targeted by your configuration.
+
+## Further Reading
+
+- [TSDoc](https://tsdoc.org)
+- [TypeDoc Tags](https://typedoc.org/documents/Tags.html)
+- [required-tags](../required-tags.md)

package/docs/rules/required-tags.md

@@ -1,76 +1,208 @@
-# required-tags
+# tsdoc-require-2/required-tags
 
-Require specific TSDoc tags to exist in TSDoc blocks for exported declarations, with optional enforcement for non-exported top-level declarations.
+> **Rule catalog ID:** R100
 
-## Rules in this family
+## Targeted pattern scope
 
+This page documents the **required-tag rule family** (`require-*`).
+
+Each `require-*` rule checks declarations that already have TSDoc and reports when its specific tag is missing.
+
+Examples:
+
+- `tsdoc-require-2/require-param` requires `@param`
+- `tsdoc-require-2/require-returns` requires `@returns`
+- `tsdoc-require-2/require-remarks` requires `@remarks`
+
+## What this rule reports
+
+For each enabled `require-*` rule, reports declarations where:
+
+- a TSDoc block exists, and
+- the required tag for that rule does not appear in the block.
+
+Like [`tsdoc-require-2/require`](./require.md), required-tag rules support declaration targeting (`enforceFor`) and export scope (`exportMode` / `includeNonExported`).
+
+## Why this rule exists
+
+Comment presence alone does not guarantee useful docs.
+
+Required-tag rules let you enforce documentation contracts such as:
+
+- every documented function has `@param` / `@returns`
+- every package entry has `@packageDocumentation`
+- every declaration includes `@remarks` for implementation context
+
+Together, these rules turn documentation from optional prose into a consistent API contract.
+
+## ❌ Incorrect
+
+```ts
+/**
+ * Creates a user record.
+ */
+export function createUser(name: string): string {
+  return name;
+}
+```
+
+With:
+
+```ts
+["error", { enforceFor: ["function"] }]
+```
+
+for `tsdoc-require-2/require-param` and `tsdoc-require-2/require-returns`.
+
+## ✅ Correct
+
+```ts
+/**
+ * Creates a user record.
+ * @param name - User display name.
+ * @returns Persisted user ID.
+ */
+export function createUser(name: string): string {
+  return name;
+}
+```
+
+## Behavior and migration notes
+
+- No single runtime rule key named `tsdoc-require-2/required-tags` exists; enable individual `require-*` rules.
+- Required-tag rules only validate comments that exist. Pair them with [`tsdoc-require-2/require`](./require.md).
+- If you also enable [`tsdoc-require-2/restrict-tags`](./restrict-tags.md) in `allow` mode, include all required tags in the allow-list to avoid policy conflicts.
+- Keep `enforceFor` and `exportMode` aligned across `require`, `require-*`, and `restrict-tags` for predictable results.
+
+## Additional examples
+
+### Shared options
+
+Each `require-*` rule accepts the same option shape:
+
+```ts
+type Options = [
+  {
+    enforceFor?: Array<
+      | "class"
+      | "enum"
+      | "function"
+      | "interface"
+      | "namespace"
+      | "object"
+      | "type"
+      | "variable"
+    >;
+    exportMode?: "all" | "exported" | "non-exported";
+    includeNonExported?: boolean;
+  },
+];
+```
+
+Default options:
+
+```ts
+[
+  {
+    enforceFor: [
+      "class",
+      "enum",
+      "function",
+      "interface",
+      "namespace",
+      "object",
+      "type",
+      "variable",
+    ],
+    exportMode: "exported",
+  },
+]
+```
+
+### Rules in this family
+
+- [`tsdoc-require-2/require-abstract`](./required-tags/require-abstract.md)
 - [`tsdoc-require-2/require-alpha`](./required-tags/require-alpha.md)
+- [`tsdoc-require-2/require-author`](./required-tags/require-author.md)
 - [`tsdoc-require-2/require-beta`](./required-tags/require-beta.md)
+- [`tsdoc-require-2/require-category`](./required-tags/require-category.md)
+- [`tsdoc-require-2/require-class`](./required-tags/require-class.md)
 - [`tsdoc-require-2/require-decorator`](./required-tags/require-decorator.md)
 - [`tsdoc-require-2/require-default-value`](./required-tags/require-default-value.md)
 - [`tsdoc-require-2/require-deprecated`](./required-tags/require-deprecated.md)
+- [`tsdoc-require-2/require-document`](./required-tags/require-document.md)
+- [`tsdoc-require-2/require-enum`](./required-tags/require-enum.md)
+- [`tsdoc-require-2/require-event`](./required-tags/require-event.md)
 - [`tsdoc-require-2/require-event-property`](./required-tags/require-event-property.md)
 - [`tsdoc-require-2/require-example`](./required-tags/require-example.md)
+- [`tsdoc-require-2/require-expand`](./required-tags/require-expand.md)
 - [`tsdoc-require-2/require-experimental`](./required-tags/require-experimental.md)
+- [`tsdoc-require-2/require-function`](./required-tags/require-function.md)
+- [`tsdoc-require-2/require-group`](./required-tags/require-group.md)
+- [`tsdoc-require-2/require-hidden`](./required-tags/require-hidden.md)
+- [`tsdoc-require-2/require-hideconstructor`](./required-tags/require-hideconstructor.md)
+- [`tsdoc-require-2/require-ignore`](./required-tags/require-ignore.md)
+- [`tsdoc-require-2/require-import`](./required-tags/require-import.md)
+- [`tsdoc-require-2/require-include`](./required-tags/require-include.md)
 - [`tsdoc-require-2/require-inherit-doc`](./required-tags/require-inherit-doc.md)
+- [`tsdoc-require-2/require-inline`](./required-tags/require-inline.md)
+- [`tsdoc-require-2/require-interface`](./required-tags/require-interface.md)
 - [`tsdoc-require-2/require-internal`](./required-tags/require-internal.md)
 - [`tsdoc-require-2/require-label`](./required-tags/require-label.md)
+- [`tsdoc-require-2/require-license`](./required-tags/require-license.md)
 - [`tsdoc-require-2/require-link`](./required-tags/require-link.md)
+- [`tsdoc-require-2/require-merge-module-with`](./required-tags/require-merge-module-with.md)
+- [`tsdoc-require-2/require-module`](./required-tags/require-module.md)
+- [`tsdoc-require-2/require-namespace`](./required-tags/require-namespace.md)
+- [`tsdoc-require-2/require-overload`](./required-tags/require-overload.md)
 - [`tsdoc-require-2/require-override`](./required-tags/require-override.md)
 - [`tsdoc-require-2/require-package-documentation`](./required-tags/require-package-documentation.md)
 - [`tsdoc-require-2/require-param`](./required-tags/require-param.md)
+- [`tsdoc-require-2/require-primary-export`](./required-tags/require-primary-export.md)
+- [`tsdoc-require-2/require-private`](./required-tags/require-private.md)
 - [`tsdoc-require-2/require-private-remarks`](./required-tags/require-private-remarks.md)
+- [`tsdoc-require-2/require-property`](./required-tags/require-property.md)
+- [`tsdoc-require-2/require-protected`](./required-tags/require-protected.md)
 - [`tsdoc-require-2/require-public`](./required-tags/require-public.md)
 - [`tsdoc-require-2/require-readonly`](./required-tags/require-readonly.md)
 - [`tsdoc-require-2/require-remarks`](./required-tags/require-remarks.md)
 - [`tsdoc-require-2/require-returns`](./required-tags/require-returns.md)
 - [`tsdoc-require-2/require-sealed`](./required-tags/require-sealed.md)
 - [`tsdoc-require-2/require-see`](./required-tags/require-see.md)
+- [`tsdoc-require-2/require-since`](./required-tags/require-since.md)
+- [`tsdoc-require-2/require-sort-strategy`](./required-tags/require-sort-strategy.md)
+- [`tsdoc-require-2/require-summary`](./required-tags/require-summary.md)
+- [`tsdoc-require-2/require-template`](./required-tags/require-template.md)
 - [`tsdoc-require-2/require-throws`](./required-tags/require-throws.md)
 - [`tsdoc-require-2/require-type-param`](./required-tags/require-type-param.md)
+- [`tsdoc-require-2/require-use-declared-type`](./required-tags/require-use-declared-type.md)
 - [`tsdoc-require-2/require-virtual`](./required-tags/require-virtual.md)
 
-## Shared options
-
-Each rule accepts the same option shape:
+## ESLint flat config example
 
 ```ts
-[
-    {
-        enforceFor?: Array<
-            | "class"
-            | "enum"
-            | "function"
-            | "interface"
-            | "object"
-            | "type"
-            | "variable"
-        >;
-        includeNonExported?: boolean;
+import tsdocRequire from "eslint-plugin-tsdoc-require-2";
+
+export default [
+  tsdocRequire.configs.recommended,
+  {
+    rules: {
+      "tsdoc-require-2/require-param": ["error", { enforceFor: ["function"] }],
+      "tsdoc-require-2/require-returns": ["error", { enforceFor: ["function"] }],
+      "tsdoc-require-2/require-throws": ["error", { enforceFor: ["function"] }],
     },
-]
+  },
+];
 ```
 
-Default:
+## When not to use it
 
-```ts
-[
-    {
-        enforceFor: [
-            "class",
-            "enum",
-            "function",
-            "interface",
-            "object",
-            "type",
-            "variable",
-        ],
-        includeNonExported: false,
-    },
-]
-```
+If your team prefers free-form narrative comments and does not want tag-level structure, required-tag rules may add noise.
+
+In that case, keep `tsdoc-require-2/require` enabled and only add the strict tag rules that provide clear value.
 
-- `enforceFor`: limits which declaration kinds are checked.
-- `includeNonExported`: when `true`, also checks non-exported top-level declarations.
+## Further reading
 
-For behavior and examples, open each individual rule document linked above.
+- [TSDoc](https://tsdoc.org)
+- [Rule family: require](./require.md)
+- [Rule family: restrict-tags](./restrict-tags.md)

package/docs/rules/restrict-tags.md

@@ -0,0 +1,203 @@
+# tsdoc-require-2/restrict-tags
+
+Restrict which tags are allowed in TSDoc blocks using allow/deny lists.
+
+> **Rule catalog ID:** R002
+
+## Targeted pattern scope
+
+This rule checks supported TypeScript declarations and default exports **that already have TSDoc block comments**.
+
+By default, it runs on exported declarations and default exports. You can widen or narrow scope with `exportMode` and `enforceFor`.
+
+## What this rule reports
+
+This rule supports two modes:
+
+- `deny`: configured tags are forbidden.
+- `allow`: only configured tags are permitted.
+
+Default mode is `deny`, with a default blocked set focused on TypeDoc compatibility tags:
+
+- `@augments`
+- `@callback`
+- `@extends`
+- `@jsx`
+- `@satisfies`
+- `@type`
+- `@typedef`
+- `@yields`
+
+## Why this rule exists
+
+A docs policy needs both **required information** and **controlled vocabulary**.
+
+`restrict-tags` prevents drift from your chosen documentation standard by blocking unsupported tags or enforcing an explicit allow-list.
+
+Use it with:
+
+- [`tsdoc-require-2/require`](./require.md) to enforce comment presence.
+- [`require-*` rules](./required-tags.md) to enforce mandatory tags.
+
+## ❌ Incorrect
+
+```ts
+/**
+ * Calculates a value.
+ * @typedef ResultShape
+ */
+export function calculate(): number {
+  return 1;
+}
+```
+
+With default configuration (`mode: "deny"`).
+
+## ✅ Correct
+
+```ts
+/**
+ * Calculates a value.
+ * @remarks Uses plain TSDoc tags.
+ */
+export function calculate(): number {
+  return 1;
+}
+```
+
+With default configuration (`mode: "deny"`).
+
+## Behavior and migration notes
+
+- This rule does not require comments on its own; it only validates tags found inside existing TSDoc blocks.
+- In `allow` mode, any tag not listed in `tags` is reported.
+- If you combine `allow` mode with required-tag rules, include all required tags in the allow-list or the rules will conflict.
+- Keep `enforceFor` and `exportMode` aligned with `require` and `require-*` rules for consistent policy.
+
+## Additional examples
+
+### Options
+
+```ts
+type Options = [
+  {
+    enforceFor?: Array<
+      | "class"
+      | "enum"
+      | "function"
+      | "interface"
+      | "namespace"
+      | "object"
+      | "type"
+      | "variable"
+    >;
+    exportMode?: "all" | "exported" | "non-exported";
+    includeNonExported?: boolean;
+    mode?: "allow" | "deny";
+    tags?: Array<`@${string}`>;
+  },
+];
+```
+
+Default options:
+
+```ts
+[
+  {
+    enforceFor: [
+      "class",
+      "enum",
+      "function",
+      "interface",
+      "namespace",
+      "object",
+      "type",
+      "variable",
+    ],
+    exportMode: "exported",
+    mode: "deny",
+    tags: [
+      "@augments",
+      "@callback",
+      "@extends",
+      "@jsx",
+      "@satisfies",
+      "@type",
+      "@typedef",
+      "@yields",
+    ],
+  },
+]
+```
+
+### Allow mode example
+
+#### Invalid in allow mode
+
+```ts
+/**
+ * Calculates a value.
+ * @remarks Useful details.
+ * @deprecated Use newCalculate instead.
+ */
+export function calculate(): number {
+  return 1;
+}
+```
+
+With:
+
+```ts
+["error", { mode: "allow", tags: ["@remarks"] }]
+```
+
+#### Valid in allow mode
+
+```ts
+/**
+ * Calculates a value.
+ * @remarks Useful details.
+ */
+export function calculate(): number {
+  return 1;
+}
+```
+
+With:
+
+```ts
+["error", { mode: "allow", tags: ["@remarks"] }]
+```
+
+## ESLint flat config example
+
+```ts
+import tsdocRequire from "eslint-plugin-tsdoc-require-2";
+
+export default [
+  tsdocRequire.configs.tsdoc,
+  {
+    rules: {
+      "tsdoc-require-2/restrict-tags": [
+        "error",
+        {
+          mode: "deny",
+          tags: ["@typedef", "@callback"],
+        },
+      ],
+    },
+  },
+];
+```
+
+## When not to use it
+
+If your team intentionally allows free-form mixtures of TSDoc, JSDoc, and TypeDoc tags, this rule can create unnecessary friction.
+
+In that case, keep required-tag rules only for tags you truly need.
+
+## Further reading
+
+- [TSDoc](https://tsdoc.org)
+- [TypeDoc tags reference](https://typedoc.org/documents/Tags.html)
+- [Rule family: required-tags](./required-tags.md)