@silverassist/agents-toolkit 2.5.0 → 2.6.0

package/templates/shared/skills/tsdoc-standards/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: tsdoc-standards
+description: Write and enforce TSDoc (not JSDoc) in TypeScript. Use when adding or reviewing doc comments on functions, components, interfaces, or file headers. Covers allowed tags, forbidden JSDoc patterns, and templates.
+---
+
+# Silver Assist — TSDoc Standards
+
+This skill is the deep reference for writing and reviewing documentation comments in
+TypeScript. All doc comments follow the **[TSDoc](https://tsdoc.org/)** standard — **not
+JSDoc**. The enforced, always-on rules live in `tsdoc-standards.instructions.md`
+(`applyTo: "**/*.{ts,tsx}"`); this skill adds the *why*, expanded examples, and a review
+checklist for on-demand use.
+
+## When to Use
+
+- Adding doc comments to functions, Server Actions, React components, hooks, or utilities
+- Documenting interfaces, types, enums, or module/file headers
+- Reviewing a PR and deciding whether a comment is TSDoc-correct
+- Migrating an existing file from JSDoc (`{type}` braces, `@template`, `@module`) to TSDoc
+- Answering "which tag do I use for X?" or "is `@fileoverview` allowed?"
+
+## Why TSDoc, not JSDoc
+
+TypeScript already carries the type information. JSDoc duplicates it in `{braces}`, which:
+
+- **Drifts** — the `{string}` in the comment and the `: string` in the signature diverge over time.
+- **Is redundant** — editors and `tsc` read the real types; the comment adds nothing.
+- **Breaks API extractors** — tools like [API Extractor](https://api-extractor.com/) and the
+  TSDoc parser reject JSDoc-only tags (`@typedef`, `@callback`, `@fileoverview`).
+
+TSDoc keeps prose in the comment and types in the code — one source of truth for each.
+
+## Core Rules (with rationale)
+
+### 1. No type annotations in `@param` / `@returns`
+
+The type is in the signature; the comment describes *meaning*, not *type*.
+
+```typescript
+// ❌ JSDoc — the {string} duplicates the signature
+/** @param {string} slug - Community slug */
+
+// ✅ TSDoc — hyphen required after the name; no braces
+/** @param slug - Community slug */
+```
+
+### 2. `@typeParam` for generics (not `@template`)
+
+```typescript
+// ❌ @template is a JSDoc/Closure tag
+/** @template T */
+
+// ✅ TSDoc generic parameter
+/** @typeParam T - The item shape returned by the fetcher */
+```
+
+### 3. `@packageDocumentation` for file/module headers (not `@module`)
+
+Place it in the **first** comment of the file. It marks module-level docs for extractors.
+
+```typescript
+/**
+ * @packageDocumentation
+ * CCDS geo-search utilities for state, city, and community lookups.
+ */
+```
+
+### 4. Document interface members inline (not `@property`)
+
+Each member gets its own leading comment — it shows on hover for that specific field.
+
+```typescript
+interface Community {
+  /** The community name. */
+  name: string;
+  /** The city where the community is located. */
+  city: string;
+  /** @defaultValue `false` */
+  featured?: boolean;
+}
+```
+
+### 5. Overloaded functions — document each overload signature
+
+For overloaded functions, place the TSDoc comment on **each overload signature individually**.
+Do **not** place it on the implementation signature — tooling (editors, `tsc`, API extractors)
+will not surface it to consumers, who only see the overload signatures.
+
+```typescript
+// ✅ TSDoc on each overload; implementation signature is undocumented
+/**
+ * Fetches a community by its slug.
+ *
+ * @param slug - The community slug
+ * @returns The matching community, or `undefined`
+ */
+export function getCommunity(slug: string): Community | undefined;
+/**
+ * Fetches a community by its numeric ID.
+ *
+ * @param id - The community ID
+ * @returns The matching community, or `undefined`
+ */
+export function getCommunity(id: number): Community | undefined;
+export function getCommunity(key: string | number): Community | undefined {
+  // implementation
+}
+```
+
+## Allowed Tags — quick reference
+
+| Tag | Format | Notes |
+|-----|--------|-------|
+| `@param` | `@param name - Description` | Hyphen required; no type braces |
+| `@returns` | `@returns Description` | No type braces |
+| `@remarks` | Block | Extended description / side effects |
+| `@example` | Block | Fenced code (` ```typescript `) |
+| `@throws` | Block | Documented exceptions |
+| `@see` | Block | Cross-reference or URL |
+| `@deprecated` | Block | Add migration guidance |
+| `@defaultValue` | Block | Default of a property |
+| `@typeParam` | `@typeParam T - Description` | Generic parameter |
+| `@packageDocumentation` | Modifier | First comment in the file |
+| `{@link symbol}` | Inline | Hyperlink to a symbol |
+
+> `@param` / `@returns` are **optional** — add them only when they add clarity (non-obvious
+> params, complex return shapes). Never add them to interfaces, types, or constants.
+
+## Templates
+
+### Server Action
+
+````typescript
+/**
+ * Submits the contact form and sends a notification email.
+ *
+ * @remarks
+ * Validates server-side, creates a DB record, dispatches email.
+ *
+ * @param formData - Submitted form data from the contact page
+ *
+ * @throws When the email service is unavailable
+ */
+export async function submitContactForm(formData: FormData): Promise<void> {}
+````
+
+### React Component
+
+````typescript
+/**
+ * Renders a responsive community card with name and location.
+ *
+ * @returns The community card JSX element
+ *
+ * @example
+ * ```tsx
+ * <CommunityCard community={community} className="mt-4" />
+ * ```
+ */
+export function CommunityCard({ community, className }: CommunityCardProps) {
+  return <article className={className}>{community.name}</article>;
+}
+````
+
+### Utility Function
+
+````typescript
+/**
+ * Formats a date string for display.
+ *
+ * @param dateString - ISO 8601 date string
+ * @returns Human-readable date (e.g., "January 15, 2025")
+ *
+ * @example
+ * ```typescript
+ * formatDate("2025-01-15"); // "January 15, 2025"
+ * ```
+ */
+export function formatDate(dateString: string): string {
+  return new Date(dateString).toLocaleDateString("en-US", { dateStyle: "long" });
+}
+````
+
+### Generic Utility (`@typeParam`)
+
+````typescript
+/**
+ * Returns the first element matching the predicate, or `undefined`.
+ *
+ * @typeParam T - The element type of the array
+ * @param items - The array to search
+ * @param predicate - Returns `true` for the desired element
+ * @returns The first matching element, or `undefined` if none match
+ */
+export function findFirst<T>(items: T[], predicate: (item: T) => boolean): T | undefined {
+  return items.find(predicate);
+}
+````
+
+## Forbidden Patterns → Fixes
+
+| ❌ Forbidden (JSDoc) | ✅ TSDoc fix |
+|----------------------|--------------|
+| `@param {string} name` | `@param name` |
+| `@returns {boolean} …` | `@returns …` |
+| `@template T` | `@typeParam T` |
+| `@module path/to/mod` | `@packageDocumentation` |
+| `@fileoverview …` | `@packageDocumentation` |
+| `@typedef {Object} X` | Define a TypeScript `interface`/`type` |
+| `@callback X` | Define a TypeScript function type |
+| `@type {X}` | Annotate the value: `const x: X = …` |
+| `@property {T} name` | Inline `/** … */` on the interface member |
+| `@function` / `@async` / `@class` / `@enum` | Remove — redundant with TypeScript |
+
+## Review Checklist
+
+When reviewing doc comments, confirm:
+
+- [ ] No `{type}` braces in `@param` / `@returns`.
+- [ ] `@param name - Description` uses the hyphen and matches the actual parameter name.
+- [ ] Generics use `@typeParam`, not `@template`.
+- [ ] File-level docs use `@packageDocumentation` in the first comment, not `@module` / `@fileoverview`.
+- [ ] Interface/type members are documented inline, not via `@property`.
+- [ ] No redundant `@function` / `@async` / `@class` / `@enum` / `@typedef` / `@callback` / `@type`.
+- [ ] `@param` / `@returns` are present only where they add real clarity.