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

package/docs/rules/require.md

@@ -1,32 +1,49 @@
 # tsdoc-require-2/require
 
-Requires TSDoc comments for exported TypeScript declarations and default exports, with optional enforcement for non-exported top-level declarations.
+Require TSDoc comments for supported TypeScript declarations and default exports, with configurable export scope.
 
-## Rule Details
+> **Rule catalog ID:** R001
 
-By default, this rule reports exported declarations that do not have a TSDoc block comment (`/** ... */`) directly above them.
+## Targeted pattern scope
+
+By default, this rule reports supported **exported** declarations that do not have a TSDoc block comment (`/** ... */`) directly above them.
+
+It evaluates top-level declarations and handles both inline exports and export specifiers.
+
+## What this rule reports
 
 It checks:
 
 - exported classes
 - exported functions
 - exported interfaces
+- exported namespaces and `declare module` declarations
 - exported type aliases
 - exported enums
 - exported variables
 - default exports (including default-exported identifiers)
 
-When `includeNonExported: true` is enabled, the same checks also apply to non-exported top-level declarations.
+For default exports, supported expression forms include function/class expressions, object expressions, and arrow functions.
+
+When `exportMode: "all"` is enabled, the same checks also apply to non-exported top-level declarations. When `exportMode: "non-exported"` is enabled, only non-exported top-level declarations are checked.
 
-Why this matters: if exported APIs are undocumented, consumers have to inspect implementation details instead of reading a stable contract.
+## Why this rule exists
 
-### ❌ Incorrect
+If exported APIs are undocumented, consumers have to infer contracts from implementation details.
+
+This rule is the foundation for the plugin’s policy model:
+
+- [`required-tags`](./required-tags.md) rules validate comment content.
+- [`restrict-tags`](./restrict-tags.md) validates tag vocabulary.
+- `require` ensures those checks have an actual comment block to validate.
+
+## ❌ Incorrect
 
 ```ts
 export class MissingDocs {}
 
 interface Shape {
-	radius: number;
+  radius: number;
 }
 
 export { Shape };
@@ -35,7 +52,7 @@ const createUser = () => ({ id: "1" });
 export default createUser;
 ```
 
-### ✅ Correct
+## ✅ Correct
 
 ```ts
 /** Public class used by external callers. */
@@ -43,7 +60,7 @@ export class DocumentedClass {}
 
 /** Shape shared in the public API. */
 interface Shape {
-	radius: number;
+  radius: number;
 }
 
 export { Shape };
@@ -53,24 +70,35 @@ const createUser = () => ({ id: "1" });
 export default createUser;
 ```
 
-## Options
+## Behavior and migration notes
+
+- Start with `exportMode: "exported"` to enforce public API docs first.
+- Expand to `"all"` when internal top-level declarations should also be documented.
+- Keep `exportMode` and `enforceFor` aligned with `require-*` and `restrict-tags` rules so documentation policy remains consistent.
+- `includeNonExported` remains supported as a legacy alias for `exportMode: "all"`, but new configurations should prefer `exportMode`.
+
+## Additional examples
+
+### Options
 
 This rule accepts one optional object.
 
 ```ts
 type Options = [
-	{
-		enforceFor?: Array<
-			"class" |
-			"enum" |
-			"function" |
-			"interface" |
-			"object" |
-			"type" |
-			"variable"
-		>;
-		includeNonExported?: boolean;
-	},
+  {
+    enforceFor?: Array<
+      "class" |
+      "enum" |
+      "function" |
+      "interface" |
+      "namespace" |
+      "object" |
+      "type" |
+      "variable"
+    >;
+    exportMode?: "all" | "exported" | "non-exported";
+    includeNonExported?: boolean;
+  },
 ];
 ```
 
@@ -78,10 +106,10 @@ Default options:
 
 ```ts
 [
-	{
-		enforceFor: ["class", "enum", "function", "interface", "object", "type", "variable"],
-		includeNonExported: false,
-	},
+  {
+    enforceFor: ["class", "enum", "function", "interface", "namespace", "object", "type", "variable"],
+    exportMode: "exported",
+  },
 ]
 ```
 
@@ -95,25 +123,29 @@ Example flat config that only enforces docs for classes and functions:
 import tsdocRequire from "eslint-plugin-tsdoc-require-2";
 
 export default [
-	{
-		plugins: {
-			"tsdoc-require-2": tsdocRequire,
-		},
-		rules: {
-			"tsdoc-require-2/require": [
-				"error",
-				{
-					enforceFor: ["class", "function"],
-				},
-			],
-		},
-	},
+  {
+    plugins: {
+      "tsdoc-require-2": tsdocRequire,
+    },
+    rules: {
+      "tsdoc-require-2/require": [
+        "error",
+        {
+          enforceFor: ["class", "function"],
+        },
+      ],
+    },
+  },
 ];
 ```
 
-### `includeNonExported`
+### `exportMode`
+
+Controls whether the rule checks exported declarations, non-exported top-level declarations, or both.
 
-When `true`, this rule also enforces TSDoc on supported non-exported top-level declarations.
+- `"exported"` (default): check exported declarations and default exports.
+- `"non-exported"`: only check supported non-exported top-level declarations.
+- `"all"`: check both exported and non-exported top-level declarations.
 
 Example flat config:
 
@@ -121,27 +153,31 @@ Example flat config:
 import tsdocRequire from "eslint-plugin-tsdoc-require-2";
 
 export default [
-	{
-		plugins: {
-			"tsdoc-require-2": tsdocRequire,
-		},
-		rules: {
-			"tsdoc-require-2/require": [
-				"error",
-				{
-					includeNonExported: true,
-				},
-			],
-		},
-	},
+  {
+    plugins: {
+      "tsdoc-require-2": tsdocRequire,
+    },
+    rules: {
+      "tsdoc-require-2/require": [
+        "error",
+        {
+          exportMode: "all",
+        },
+      ],
+    },
+  },
 ];
 ```
 
-## When Not To Use It
+### `includeNonExported`
+
+`includeNonExported` is still supported as a backward-compatible alias for `exportMode: "all"`. Prefer `exportMode` in new configurations because it can also express `"non-exported"` explicitly.
+
+## When not to use it
 
 Disable this rule if your project intentionally does not require API documentation on exported declarations (or internal declarations when `includeNonExported` is enabled).
 
-## Further Reading
+## Further reading
 
 - [TSDoc](https://tsdoc.org)
 - [ESLint custom rule docs](https://eslint.org/docs/latest/extend/custom-rules)

package/docs/rules/required-tags/require-abstract.md

@@ -0,0 +1,87 @@
+# tsdoc-require-2/require-abstract
+
+Require the `@abstract` 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 `@abstract`. 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.
+ * @abstract
+ */
+export function taggedFunction(value: string): string {
+    return value;
+}
+```
+
+## When Not To Use It
+
+Disable this rule if your documentation convention does not require `@abstract` 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/require-alpha.md

@@ -54,4 +54,4 @@ export function runTask(value: string): string {
 ## Further reading
 
 - TSDoc tag reference: <https://tsdoc.org/pages/tags/alpha/>
-- Rule index: [required-tags](../required-tags.md)
+- Rule index: [required-tags](../required-tags.md)

package/docs/rules/required-tags/require-author.md

@@ -0,0 +1,87 @@
+# tsdoc-require-2/require-author
+
+Require the `@author` 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 `@author`. 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.
+ * @author
+ */
+export function taggedFunction(value: string): string {
+    return value;
+}
+```
+
+## When Not To Use It
+
+Disable this rule if your documentation convention does not require `@author` 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/require-beta.md

@@ -54,4 +54,4 @@ export function runTask(value: string): string {
 ## Further reading
 
 - TSDoc tag reference: <https://tsdoc.org/pages/tags/beta/>
-- Rule index: [required-tags](../required-tags.md)
+- Rule index: [required-tags](../required-tags.md)

package/docs/rules/required-tags/require-category.md

@@ -0,0 +1,87 @@
+# tsdoc-require-2/require-category
+
+Require the `@category` 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 `@category`. 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.
+ * @category
+ */
+export function taggedFunction(value: string): string {
+    return value;
+}
+```
+
+## When Not To Use It
+
+Disable this rule if your documentation convention does not require `@category` 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/require-class.md

@@ -0,0 +1,71 @@
+# tsdoc-require-2/require-class
+
+Require the `@class` tag in TSDoc blocks for supported TypeScript declarations.
+
+## Rule details
+
+This rule reports declarations that already have TSDoc but do not contain `@class`.
+
+It does not create a TSDoc block. Pair it with [`tsdoc-require-2/require`](../require.md) when you also want to require comments.
+
+## Why use it
+
+`@class` can help teams and doc generators that expect explicit declaration-kind tags.
+
+## 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"`.
+
+Flat config example (class-only scope):
+
+```ts
+import tsdocRequire from "eslint-plugin-tsdoc-require-2";
+
+export default [
+    {
+        plugins: {
+            "tsdoc-require-2": tsdocRequire,
+        },
+        rules: {
+            "tsdoc-require-2/require-class": ["error", { enforceFor: ["class"] }],
+        },
+    },
+];
+```
+
+## ❌ Incorrect
+
+```ts
+/**
+ * Represents a cache entry.
+ */
+export class CacheEntry {
+    public constructor(public readonly key: string) {}
+}
+```
+
+## ✅ Correct
+
+```ts
+/**
+ * Represents a cache entry.
+ * @class
+ */
+export class CacheEntry {
+    public constructor(public readonly key: string) {}
+}
+```
+
+## When not to use it
+
+Disable this rule if your documentation convention does not require `@class` 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/require-decorator.md

@@ -54,4 +54,4 @@ export function runTask(value: string): string {
 ## Further reading
 
 - TSDoc tag reference: <https://tsdoc.org/pages/tags/decorator/>
-- Rule index: [required-tags](../required-tags.md)
+- Rule index: [required-tags](../required-tags.md)

package/docs/rules/required-tags/require-default-value.md

@@ -54,4 +54,4 @@ export function runTask(value: string): string {
 ## Further reading
 
 - TSDoc tag reference: <https://tsdoc.org/pages/tags/defaultvalue/>
-- Rule index: [required-tags](../required-tags.md)
+- Rule index: [required-tags](../required-tags.md)

package/docs/rules/required-tags/require-deprecated.md

@@ -54,4 +54,4 @@ export function runTask(value: string): string {
 ## Further reading
 
 - TSDoc tag reference: <https://tsdoc.org/pages/tags/deprecated/>
-- Rule index: [required-tags](../required-tags.md)
+- Rule index: [required-tags](../required-tags.md)

package/docs/rules/required-tags/require-document.md

@@ -0,0 +1,87 @@
+# tsdoc-require-2/require-document
+
+Require the `@document` 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 `@document`. 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.
+ * @document
+ */
+export function taggedFunction(value: string): string {
+    return value;
+}
+```
+
+## When Not To Use It
+
+Disable this rule if your documentation convention does not require `@document` 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)