From 018339689b7a3239f1466e425e28192698577bee Mon Sep 17 00:00:00 2001 From: Dan Connolly Date: Wed, 7 Oct 2026 09:44:26 -0500 Subject: [PATCH] docs-files-api: a script that prints usage keeps its manual in HELP Refines the program-script exception: when the script prints its usage, the manual is a HELP string constant under a one-line @file (JS has no docstrings), not a comment copied into code or re-read from source. Generated-by: Claude Opus 5.5 --- docs-files-api/SKILL.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs-files-api/SKILL.md b/docs-files-api/SKILL.md index aa82483..1b23fe4 100644 --- a/docs-files-api/SKILL.md +++ b/docs-files-api/SKILL.md @@ -20,11 +20,14 @@ JSDoc placement rules (from the 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. + `import.meta.main`). The manual goes at the top: 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. If the script prints its usage, make the manual a + `HELP` string constant right under a one-line `@file` (JavaScript has + no docstrings; a string literal is the honest equivalent) rather than + copying it or reading the script's own source. 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).