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

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

@@ -0,0 +1,73 @@
+# tsdoc-require-2/require-enum
+
+Require the `@enum` tag in TSDoc blocks for supported TypeScript declarations.
+
+## Rule details
+
+This rule reports declarations that already have TSDoc but do not contain `@enum`.
+
+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
+
+`@enum` 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 (enum-only scope):
+
+```ts
+import tsdocRequire from "eslint-plugin-tsdoc-require-2";
+
+export default [
+    {
+        plugins: {
+            "tsdoc-require-2": tsdocRequire,
+        },
+        rules: {
+            "tsdoc-require-2/require-enum": ["error", { enforceFor: ["enum"] }],
+        },
+    },
+];
+```
+
+## ❌ Incorrect
+
+```ts
+/**
+ * Status values accepted by the API.
+ */
+export enum Status {
+    Ready = "ready",
+    Running = "running",
+}
+```
+
+## ✅ Correct
+
+```ts
+/**
+ * Status values accepted by the API.
+ * @enum
+ */
+export enum Status {
+    Ready = "ready",
+    Running = "running",
+}
+```
+
+## When not to use it
+
+Disable this rule if your documentation convention does not require `@enum` 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-event-property.md

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

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

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

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

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

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

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

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

@@ -0,0 +1,74 @@
+# tsdoc-require-2/require-function
+
+Require the `@function` tag in TSDoc blocks for supported TypeScript declarations.
+
+## Rule details
+
+This rule reports declarations that already have TSDoc but do not contain `@function`.
+
+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
+
+`@function` 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 (function-only scope):
+
+```ts
+import tsdocRequire from "eslint-plugin-tsdoc-require-2";
+
+export default [
+    {
+        plugins: {
+            "tsdoc-require-2": tsdocRequire,
+        },
+        rules: {
+            "tsdoc-require-2/require-function": [
+                "error",
+                { enforceFor: ["function"] },
+            ],
+        },
+    },
+];
+```
+
+## ❌ Incorrect
+
+```ts
+/**
+ * Creates a stable slug for a title.
+ */
+export function toSlug(value: string): string {
+    return value.trim().toLowerCase();
+}
+```
+
+## ✅ Correct
+
+```ts
+/**
+ * Creates a stable slug for a title.
+ * @function
+ */
+export function toSlug(value: string): string {
+    return value.trim().toLowerCase();
+}
+```
+
+## When not to use it
+
+Disable this rule if your documentation convention does not require `@function` 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-group.md

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

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

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

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