shdoc-shell-docs

# Shdoc Shell Docs ## Overview Use this skill to make shellscript comments parseable by `shdoc` without bloating simple code with boilerplate. Inspect the file first, then document the script and the non-trivial functions that benefit from generated reference docs. ## Workflow 1. Inspect the target shell file before writing comments. 2. Read `references/shdoc-rules.md` before editing comments. 3. Use `install/common/mise.sh` as the repo-local style example when working in this repository. 4. Add or repair file-level annotations near the top of the file: - Prefer `@file` for the script identifier. - Add `@brief` for a single-sentence summary. - Add multiline `@description` only when the script needs more context. 5. Add function-level annotations only where they help: - Start with `@description`. - Add `@arg` for positional parameters. - Add `@option` for flags and option-value pairs. - Add `@example` when the call shape is not obvious. - Add `@stdout`, `@stderr`, `@exitcode`, or `@see` only when they clarify observable behavior. 6. Rewrite existing free-form comments into valid `shdoc` annotations instead of keeping two parallel comment styles. ## Review Checklist - Confirm the docs match the implementation instead of guessing arguments or options. - Keep annotations immediately above the file header or function they describe. - Prefer behavior and operator-facing intent over internal implementation notes. - Skip boilerplate comments for trivial ...