Skip to main content

tsdoc-require-2/required-tags

Rule catalog ID: R100

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, 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​

/**
 * Creates a user record.
 */
export function createUser(name: string): string {
 return name;
}

With:

["error", { enforceFor: ["function"] }];

for tsdoc-require-2/require-param and tsdoc-require-2/require-returns.

✅ Correct​

/**
 * 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.
  • If you also enable tsdoc-require-2/restrict-tags 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:

type Options = [
 {
  enforceFor?: Array<
   | "class"
   | "enum"
   | "function"
   | "interface"
   | "namespace"
   | "object"
   | "type"
   | "variable"
  >;
  exportMode?: "all" | "exported" | "non-exported";
  includeNonExported?: boolean;
 },
];

Default options:

[
 {
  enforceFor: [
   "class",
   "enum",
   "function",
   "interface",
   "namespace",
   "object",
   "type",
   "variable",
  ],
  exportMode: "exported",
 },
];

Rules in this family​

ESLint flat config example​

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"] }],
  },
 },
];

When not to use it​

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.

Further reading​