bash/doc-comments
Checks that each shell function has a comment above it that says more than its name.
Part of the bash configuration, at the all level. It runs at the commit stage, per file. gspot runs this check itself.
Without a summary, the reader must trace the function in their head, and nobody trusts a vague one.
What to do
Section titled “What to do”Write “# name: what it does” above the function; when it carries doc sections, keep Globals, Arguments, Outputs, and Returns in that order.
Example
Section titled “Example”_quiet() { printf "%s\n" "Hello"; } with no comment above it reports a finding. Add # _quiet: prints a greeting. on the line above.
Turn it off
Section titled “Turn it off”Turn it off for some files, with a reason:
gspot ignore bash/doc-comments --paths "<glob>" --reason "<why>"