mad-skills/docs-files-api/SKILL.md

name, description

name	description
docs-files-api	JSDoc placement rules for TypeScript/JSDoc code — use when writing or reviewing code comments, JSDoc, or file headers; deciding where @file/@see links go; documenting exported symbols or external specs; when a `//` comment explains what a declaration is or does (it belongs in JSDoc).

Documentation Conventions

JSDoc placement rules (from the portfolio-contract contributing notes):

• File comments: Use a 1–2 line @file summary rather than a long file header essay. Include @see links only for major entry points, and keep those links intra-file (e.g. {@link someExport}), not external URLs.
• Entry-point JSDoc: Put the meaningful docs on the exported symbols — that's what shows up in IDE call sites. External URLs belong here when they define the canonical ABI/spec of the thing being exported.
• API docs are JSDoc, not //: What a function, class, method, type, field, or constant is or does goes in a /** … */ comment on its declaration — IDEs show it at call sites and on hover; a // line above the declaration shows nowhere. // is for implementation notes inside a body: the why of a non-obvious line, next to that line.
• Exception: program scripts (run directly: a shebang, or import.meta.main). The @file comment is the script's manual: a one-line purpose, a usage synopsis, the arguments, and what it writes or prints. People open a script to learn how to run it, and its main has no call sites for JSDoc to show at. Helpers inside still get their own JSDoc.
• External design constraints: If a module is constrained by external contracts, standards, or off-repo design docs, add a short JSDoc note with a @see link to the authoritative source at the relevant entry point(s).

In short: brief at the top of the file, meaty on exports (in JSDoc), // only for the why inside bodies, @see to authoritative external sources only where they define the contract.