Skip to content

Shdoc

Index

shdoc::_header_end_line

Print the last line number of a script's file-level shdoc header window. The window runs from the shebang to the first set -Eeuo pipefail line; standalone misc/ scripts that omit that pragma fall back to 30 lines. Shared by shdoc::file_has_description and shdoc::header_has_placeholder so the two cannot drift apart.

Arguments

  • $1 (file): path to script

Output on stdout

  • The header window's end line number.

shdoc::file_has_description

Return true if the given script file carries an # @description shdoc tag in its file-level header — i.e. somewhere between the shebang line and either the first set -Eeuo pipefail line or, for standalone misc/ scripts that omit that pragma, within the first 30 lines.

Arguments

  • $1 (file): path to script

Exit codes

  • 0: if a # @description line is found in the header window
  • 1: otherwise

shdoc::find_unannotated_functions

Scan a script file for top-level helper function definitions of the form function NAME() { and print the names of any whose immediately preceding non-blank, non-shellcheck-directive line is NOT a shdoc tag line (does not match ^# @). Names may be namespaced with ::, which every function in functions/*.bash is; omitting the colon from the name class would make the library arm of check-shdoc-headers match nothing at all. The literal main function is always excluded — it is covered by the file-level header per project rule.

Arguments

  • $1 (file): path to script

Exit codes

  • 0: always (presence of unannotated functions is signaled via stdout)

Output on stdout

  • names of unannotated helper functions, one per line

shdoc::header_has_placeholder

Return true if a script's file-level shdoc header contains placeholder text. Scanning starts at the first # @ tag line inside the header window and covers every comment line from there on, so tag bodies and their indented continuations are both checked. The match is a case-sensitive, word-bounded TODO; a backtick-quoted one is prose about the token and is allowed, so todo, TODOS, and `TODO` do not trip it. The pattern is shared with shdoc::find_placeholder_functions via shdoc::_placeholder_gawk_pattern. Content outside the header window is ignored — that is what exempts new-script, whose scaffold template lives in a heredoc well past its own pragma line.

Arguments

  • $1 (file): path to script

Exit codes

  • 0: placeholder text found in the header window
  • 1: no placeholder text in the header window

shdoc::_placeholder_gawk_pattern

Print the gawk-compatible ERE that matches placeholder text in an shdoc annotation. A bare, case-sensitive, word-bounded TODO is a placeholder; a backtick-quoted one is prose about the token and is deliberately allowed, so that helpers documenting this very rule can name it. Underscore counts as a word character, so TODO_MARKER is not a placeholder either. Defined once and shared by shdoc::header_has_placeholder and shdoc::find_placeholder_functions so the file-level and per-function checks cannot drift apart, the same reason shdoc::_header_end_line is shared.

Function has no arguments.

Output on stdout

  • The regular expression.

shdoc::find_placeholder_functions

Scan a script or library file for top-level function definitions of the form function NAME() { and print the names of any whose contiguous preceding comment block contains placeholder text, per shdoc::_placeholder_gawk_pattern. The block is every unbroken comment line immediately above the definition; a blank or non-comment line ends it, so a detached note further up the file is not attributed to the function. Applies to both library files and top-level scripts: a helper inside a top-level script has an annotation block too, and scanning only the file-level header would miss it. The literal main function is excluded, mirroring shdoc::find_unannotated_functions so both helpers select functions identically.

Arguments

  • $1 (file): path to script or library file

Exit codes

  • 0: always (presence of placeholders is signaled via stdout)

Output on stdout

  • names of functions whose annotation carries placeholder text, one per line