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

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

@@ -1,29 +1,40 @@
 # tsdoc-require-2/require-remarks
 
-Require the `@remarks` tag in TSDoc blocks for exported declarations.
+Require the `@remarks` 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 `@remarks`. Set `includeNonExported: true` to also check non-exported top-level declarations.
+This rule reports declarations that already have TSDoc but are missing `@remarks`.
 
-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
+
+`@remarks` captures context that does not fit in a one-line summary, such as caveats, migration notes, or runtime assumptions.
 
 ## Options
 
-```json
-{
-  "rules": {
-    "tsdoc-require-2/require-remarks": [
-      "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:
+
+```ts
+import tsdocRequire from "eslint-plugin-tsdoc-require-2";
+
+export default [
+  {
+    plugins: {
+      "tsdoc-require-2": tsdocRequire,
+    },
+    rules: {
+      "tsdoc-require-2/require-remarks": "error",
+    },
+  },
+];
 ```
 
 ## Examples
@@ -32,10 +43,10 @@ It supports the same options as [`tsdoc-require-2/require`](../require.md):
 
 ```ts
 /**
- * Performs a task.
+ * Loads the project configuration.
  */
-export function runTask(value: string): string {
-  return value;
+export function loadConfig(): string {
+  return "default";
 }
 ```
 
@@ -43,15 +54,19 @@ export function runTask(value: string): string {
 
 ```ts
 /**
- * Performs a task.
- * @remarks
+ * Loads the project configuration.
+ * @remarks Falls back to default values when no config file exists.
  */
-export function runTask(value: string): string {
-  return value;
+export function loadConfig(): string {
+  return "default";
 }
 ```
 
+## Behavior notes
+
+This rule checks tag presence. It does not validate the depth or quality of the remarks text.
+
 ## Further reading
 
-- TSDoc tag reference: <https://tsdoc.org/pages/tags/remarks/>
-- Rule index: [required-tags](../required-tags.md)
+- [TSDoc tag reference: @remarks](https://tsdoc.org/pages/tags/remarks/)
+- [required-tags family overview](../required-tags.md)

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

@@ -1,29 +1,45 @@
 # tsdoc-require-2/require-returns
 
-Require the `@returns` tag in TSDoc blocks for exported declarations.
+Require the `@returns` 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 `@returns`. Set `includeNonExported: true` to also check non-exported top-level declarations.
+This rule reports declarations that already have TSDoc but are missing `@returns`.
 
-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
+
+`@returns` makes output contracts explicit and easier to review.
 
 ## Options
 
-```json
-{
-  "rules": {
-    "tsdoc-require-2/require-returns": [
-      "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-returns": [
+        "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.
- * @returns
+ * Converts input to a stable ID.
+ * @returns Lower-cased stable ID.
  */
-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 return description quality or return-type accuracy.
+
 ## Further reading
 
-- TSDoc tag reference: <https://tsdoc.org/pages/tags/returns/>
-- Rule index: [required-tags](../required-tags.md)
+- [TSDoc tag reference: @returns](https://tsdoc.org/pages/tags/returns/)
+- [required-tags family overview](../required-tags.md)

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

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

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

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

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

@@ -1,29 +1,45 @@
 # tsdoc-require-2/require-throws
 
-Require the `@throws` tag in TSDoc blocks for exported declarations.
+Require the `@throws` 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 `@throws`. Set `includeNonExported: true` to also check non-exported top-level declarations.
+This rule reports declarations that already have TSDoc but are missing `@throws`.
 
-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
+
+`@throws` documents failure behavior and reduces hidden runtime surprises for consumers.
 
 ## Options
 
-```json
-{
-  "rules": {
-    "tsdoc-require-2/require-throws": [
-      "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-throws": [
+        "error",
+        {
+          enforceFor: ["function"],
+        },
+      ],
+    },
+  },
+];
 ```
 
 ## Examples
@@ -32,10 +48,14 @@ It supports the same options as [`tsdoc-require-2/require`](../require.md):
 
 ```ts
 /**
- * Performs a task.
+ * Loads a user by ID.
  */
-export function runTask(value: string): string {
-  return value;
+export function loadUser(id: string): string {
+  if (id.length === 0) {
+    throw new Error("id is required");
+  }
+
+  return id;
 }
 ```
 
@@ -43,15 +63,23 @@ export function runTask(value: string): string {
 
 ```ts
 /**
- * Performs a task.
- * @throws
+ * Loads a user by ID.
+ * @throws Error when the id is empty.
  */
-export function runTask(value: string): string {
-  return value;
+export function loadUser(id: string): string {
+  if (id.length === 0) {
+    throw new Error("id is required");
+  }
+
+  return id;
 }
 ```
 
+## Behavior notes
+
+This rule checks tag presence. It does not verify whether code paths actually throw.
+
 ## Further reading
 
-- TSDoc tag reference: <https://tsdoc.org/pages/tags/throws/>
-- Rule index: [required-tags](../required-tags.md)
+- [TSDoc tag reference: @throws](https://tsdoc.org/pages/tags/throws/)
+- [required-tags family overview](../required-tags.md)