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

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

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

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

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

@@ -1,29 +1,45 @@
 # tsdoc-require-2/require-package-documentation
 
-Require the `@packageDocumentation` tag in TSDoc blocks for exported declarations.
+Require the `@packageDocumentation` 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 `@packageDocumentation`. Set `includeNonExported: true` to also check non-exported top-level declarations.
+This rule reports declarations that already have TSDoc but are missing `@packageDocumentation`.
 
-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
+
+`@packageDocumentation` helps establish package-level intent and usage context in generated docs.
 
 ## Options
 
-```json
-{
-  "rules": {
-    "tsdoc-require-2/require-package-documentation": [
-      "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 (namespace/module focused):
+
+```ts
+import tsdocRequire from "eslint-plugin-tsdoc-require-2";
+
+export default [
+  {
+    plugins: {
+      "tsdoc-require-2": tsdocRequire,
+    },
+    rules: {
+      "tsdoc-require-2/require-package-documentation": [
+        "error",
+        {
+          enforceFor: ["namespace"],
+        },
+      ],
+    },
+  },
+];
 ```
 
 ## Examples
@@ -32,10 +48,10 @@ It supports the same options as [`tsdoc-require-2/require`](../require.md):
 
 ```ts
 /**
- * Performs a task.
+ * Public API surface for this package.
  */
-export function runTask(value: string): string {
-  return value;
+export namespace Api {
+  export type Id = string;
 }
 ```
 
@@ -43,15 +59,19 @@ export function runTask(value: string): string {
 
 ```ts
 /**
- * Performs a task.
+ * Public API surface for this package.
  * @packageDocumentation
  */
-export function runTask(value: string): string {
-  return value;
+export namespace Api {
+  export type Id = string;
 }
 ```
 
+## Behavior notes
+
+This rule checks tag presence. It does not enforce where package documentation should be physically located.
+
 ## Further reading
 
-- TSDoc tag reference: <https://tsdoc.org/pages/tags/packagedocumentation/>
-- Rule index: [required-tags](../required-tags.md)
+- [TSDoc tag reference: @packageDocumentation](https://tsdoc.org/pages/tags/packagedocumentation/)
+- [required-tags family overview](../required-tags.md)

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

@@ -1,29 +1,45 @@
 # tsdoc-require-2/require-param
 
-Require the `@param` tag in TSDoc blocks for exported declarations.
+Require the `@param` 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 `@param`. Set `includeNonExported: true` to also check non-exported top-level declarations.
+This rule reports declarations that already have TSDoc but are missing `@param`.
 
-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
+
+`@param` documents input meaning and reduces ambiguity at call sites.
 
 ## Options
 
-```json
-{
-  "rules": {
-    "tsdoc-require-2/require-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 (function-focused scope):
+
+```ts
+import tsdocRequire from "eslint-plugin-tsdoc-require-2";
+
+export default [
+  {
+    plugins: {
+      "tsdoc-require-2": tsdocRequire,
+    },
+    rules: {
+      "tsdoc-require-2/require-param": [
+        "error",
+        {
+          enforceFor: ["function"],
+        },
+      ],
+    },
+  },
+];
 ```
 
 ## Examples
@@ -32,10 +48,10 @@ It supports the same options as [`tsdoc-require-2/require`](../require.md):
 
 ```ts
 /**
- * Performs a task.
+ * Converts input to a stable ID.
  */
-export function runTask(value: string): string {
-  return value;
+export function toStableId(value: string): string {
+  return value.trim().toLowerCase();
 }
 ```
 
@@ -43,15 +59,19 @@ export function runTask(value: string): string {
 
 ```ts
 /**
- * Performs a task.
- * @param
+ * Converts input to a stable ID.
+ * @param value - Raw identifier input.
  */
-export function runTask(value: string): string {
-  return value;
+export function toStableId(value: string): string {
+  return value.trim().toLowerCase();
 }
 ```
 
+## Behavior notes
+
+This rule checks tag presence. It does not validate one `@param` entry per function parameter.
+
 ## Further reading
 
-- TSDoc tag reference: <https://tsdoc.org/pages/tags/param/>
-- Rule index: [required-tags](../required-tags.md)
+- [TSDoc tag reference: @param](https://tsdoc.org/pages/tags/param/)
+- [required-tags family overview](../required-tags.md)

package/docs/rules/required-tags/require-primary-export.md

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

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

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

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