doc-elements

a tag carrying what its type already says, or a description repeating the code

Agent checkadvisory by defaultbasecode

The argument

Elements

Description: one or two sentences — what it does and why you'd use it. Focus on why; the code shows what.
@param: name and purpose only — TypeScript owns the type. For object-args functions, @param tags document the destructured property names directly. Sentence fragments, lowercase.
@throws: only errors intentionally thrown and expected to be caught: @throws {ConnectionError} When the database is unreachable.
@returns: only when the value has semantics the type doesn't show (a string that is a JWT; a boolean where true means "already existed").
@example: for complex APIs or non-obvious usage; minimal and runnable.
@typeParam: when a generic's purpose isn't obvious from its name.

Complete Example

interface Params<T> {
	fn: () => Promise<T>;
	maxAttempts?: number;
	baseDelay?: number;
}

/**
 * Retries an async operation with exponential backoff.
 *
 * Useful for network requests that may fail transiently.
 *
 * @param fn - async function to retry
 * @param maxAttempts - attempts before giving up
 * @param baseDelay - initial delay in ms, doubles after each failure
 * @throws {RetryExhaustedError} When all retry attempts fail
 */
export const retry = async <T>({ fn, maxAttempts = 3, baseDelay = 1000 }: Params<T>): Promise<T> => {
	// ...
};

The proof

failsrc/billing/chargeInvoice.ts

/**
 * Charges an invoice.
 *
 * @param invoiceId - {string} The id of the invoice, a string
 * @returns a string
 */
export const chargeInvoice = ({ invoiceId }: { invoiceId: string }): string => invoiceId;

passsrc/billing/chargeInvoice.ts

/**
 * Charges an invoice against the payer's default method.
 *
 * @param invoiceId - the invoice to charge
 * @throws {PaymentDeclinedError} When the payment method refuses the charge
 */
export const chargeInvoice = ({ invoiceId }: { invoiceId: string }): string => invoiceId;

Turn it down

Both lines go in your lightsout.config.json.

"standards-checks": { "doc-elements": "advisory" }

"standards-checks": { "doc-elements": "off" }