From da4e709ef4132ce4798615506cb202814c501872 Mon Sep 17 00:00:00 2001 From: Dan Connolly Date: Wed, 7 Oct 2026 09:37:19 -0500 Subject: [PATCH] docs-files-api: program scripts' @file is their manual The exception: a script run directly (shebang or import.meta.main) puts its purpose, usage synopsis, arguments, and outputs in @file. Readers open a script to learn how to run it; its main has no call sites for JSDoc to show at. Generated-by: Claude Opus 5.5 --- docs-files-api/SKILL.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs-files-api/SKILL.md b/docs-files-api/SKILL.md index b641ef5..aa82483 100644 --- a/docs-files-api/SKILL.md +++ b/docs-files-api/SKILL.md @@ -19,6 +19,12 @@ JSDoc placement rules (from the 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).