shdoc

Converts comments to function to reference markdown documentation.

Usage

Global Script tags

shdoc will match comments in the following form on top of a script file:

#!/bin/bash
#
# @file Title of file script
# @brief Small description of the script.

Will produce following output:

Title of file script

Small description of the script.

Function tags

shdoc will match comments in the following form before function definitions:

# @description Multiline description goes here and
# there
#
# @example
#   some:other:func a b c
#   echo 123
#
# @arg $1 string Some arg.
# @arg $@ any Rest of arguments.
#
# @noargs
#
# @exitcode 0  If successfull.
# @exitcode >0 On failure
# @exitcode 5  On some error.
#
# @stdout Path to something.
#
# @see some:other:func()
some:first:func() {

shdoc.awk has no args and expects shell script with comments as described above on the stdin and will markdown output result on the stdout.

Will produce following output:

some:first:func()

Multiline description goes here and there

Example

some:other:func a b c
echo 123

Arguments

• $1 (string): Some arg.
• ... (any): Rest of arguments.

Function has no arguments.

Exit codes

• 0: If successfull.

• 0: On failure

• 5: On some error.

Output on stdout

• Path to something.

See also

• some:other:func()

Examples

See example documentation on:

• tests.sh
• coproc.bash