shdoc - Man Page

shdoc [-h|--help]
shdoc [--version]
shdoc [FILE]

shdoc reads a shell script, parses annotation comments, and writes GitHub-flavored Markdown documentation to standard output. If FILE is omitted, input is read from standard input.

Annotations are comments beginning with # @. File annotations describe the generated document. Function annotations are collected until the next shell function declaration, where the pending block is rendered. Section annotations group following functions. Function-like text inside @example blocks is ignored.

-h,  --help

Show command-line help and exit.

--version

Show version information and exit.

@name

Set the project name used as the document title.

@file

Alias for @name.

@brief

Set a short project summary.

@description

Set a multiline description for the file, current section, or next function. Continuation lines are written as comment lines after the tag.

@deprecated

Mark the next documented function as deprecated.

@section

Start a named section for following functions.

@example

Add a multiline usage example for the next function. The captured block is unindented and rendered as a Bash code fence.

@option

Describe a command-line option accepted by the function. Options may be short, long, or alternatives separated by a vertical bar.

@arg

Describe a positional argument such as $1 or $@.

@noargs

State that the function does not accept arguments.

@set

Describe a global variable set by the function.

@exitcode

Describe an exit status returned by the function.

@stdin,  @stdout,  @stderr

Describe expected standard input, standard output, or standard error. Indented comment lines continue the previous entry.

@see

Add a related function, anchor, or Markdown link to the function's "See also" section.

@internal

Skip documentation for the next annotated function.

Generate documentation from standard input:

shdoc < lib.sh > REFERENCE.md

Generate documentation from a named file:

shdoc lib.sh > REFERENCE.md

Example annotated function:

# @description Say hello to a name.
# @arg $1 string Name to greet.
# @stdout A greeting line.
say-hello() {
    echo "Hello $1"
}

shdoc exits 0 after successful generation or after printing help or version information. It exits non-zero when GNU Awk reports an error or when parsing fails.

contrib/shdoc.1

Manual page distributed with the source tree.

gawk(1)

Project homepage: https://github.com/reconquest/shdoc