From 7a9b25538b4c8e09ab86278b57b6727473fc4bb5 Mon Sep 17 00:00:00 2001 From: Dan Connolly Date: Wed, 7 Oct 2026 09:31:04 -0500 Subject: [PATCH] docs-files-api: API docs are JSDoc, not // comments What a declaration is or does goes in /** */ on it (IDEs show it at call sites and on hover); `//` is for the why of a line inside a body. The description gains the trigger: a `//` comment explaining a declaration. Generated-by: Claude Opus 5.5 --- docs-files-api/SKILL.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs-files-api/SKILL.md b/docs-files-api/SKILL.md index edfa88c..b641ef5 100644 --- a/docs-files-api/SKILL.md +++ b/docs-files-api/SKILL.md @@ -1,6 +1,6 @@ --- name: docs-files-api -description: JSDoc placement rules for TypeScript/JSDoc code — use when writing or reviewing JSDoc comments, deciding where @file/@see links go, or documenting external specs of exported symbols. +description: 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 @@ -14,9 +14,15 @@ JSDoc placement rules (from the - **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. - **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, `@see` to -authoritative external sources only where they define the contract. \ No newline at end of file +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. \ No newline at end of file