/ Documentation / ShellDoc - shell script documentation format
en

ShellDoc: shell script documentation format

ShellDoc is a simple format for Unix shell script embedded-in-comments documentation and a reference implementation of utility that collects.

ShellDoc is highly inspired with lookalike tools and formats for other languages, such as:

ShellDoc utility is a document generator – lots of other document generators are compared in Wikipedia.

Format

ShellDoc can be used to add embedded human-readable documentation (in comments) in shell script function libraries. Basic form of function documentation is illustrated below:

# Starts a monitoring in background, ensuring that running monitoring
# is unique.
#
# Input:
# $1 - name of monitoring script
# $2 - time period
# $3 - if true, then this monitoring will be time-limited
# MON_OUTPUT - if set, logging output of monitoring would be sent to designated file
#
# Output:
# number of monitorings successfully started
start_monitoring_with_period()
{
    # code here
}

Formally, all ShellDoc documentation should be included right before function declartion, escaped with # comments. There are 3 sections:

  • General description – default, not designated by anything in particular
  • Input – description of input values (call arguments, global variables), started with Input: declaration
  • Output – description of output value(s), started with Output: declaration