Shdoc Shell Docs

Overview

shdoc

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 private helpers unless the user asks for exhaustive coverage.
• Keep multiline annotation blocks compact and easy to render as Markdown.

References

• Read

  references/shdoc-rules.md

  for the minimal tag set, concise examples, and external reference policy.