shelldocs

Purpose

Some projects have complex shell functions that act as APIs. shelldocs provides an annotation system similar to JavaDoc. It allows a developer to auto-generate MultiMarkdown documentation files as input to other processing systems.

Requirements

Function Annotations

shelldocs works by doing simple parsing of shell scripts. As such, it looks for code that matches these patterns:

## @annotation
function functioname() {
  ...
}

## @annotation
function functioname () {
  ...
}

## @annotation
function functioname {
  ...
}

## @annotation
function functioname
{
  ...
}

## @annotation
functioname() {
  ...
}

## @annotation
functioname () {
  ...
}

Note that the comment has two hash ('#') marks. The content of the comment is key. This is what shelldocs will turn into documentation. The following annotations are supported:

Annotation Required Description Acceptable Values Default
@description No What this function does, intended purpose, etc. text None
@audience Yes Who should use this function? public, private, None
@stability Yes Is this function going to change? stable, evolving None
@replaceable No Is this function safely 'monkeypatched'? yes or no No
@param No A single parameter A single keyword. e.g., 'seconds' to specify that this function requires a time in seconds None
@return No What does this function return? text Nothing

Audience / Stability

This values are the shell equivalents to the Java versions present in Apache Yetus Audience Annotations.

Multiple Parameters

Each parameter requires it's own @param line and they must be listed in order.

Return Values

It is recommended that multiple @return entries should be used when multiple values are possible. For example:

## @return 0 - success
## @return 1 - failure

Code Example

## @description This is an example
## @description of what one can do.
## @audience public
## @stability stable
## @param integer
## @param integer
## @return sum
function add_two_numbers() {
  return (($1 + $2))
}

Basic Usage

The shelldocs executable requires at least one input file and either an output file or to run in lint mode. Lint mode is covered below.

$ shelldocs --output functions.md --input myshelldirectory

This will process all of the files in myshelldirectory that end in sh and generate an output file called functions.md. This file will contain a table of contents of all of the functions arranged by audience, stability, and replace-ability.

Skipping Files

When processing directories, it may be desirable to avoid certain files. This may be done by including a comment in the file:

# SHELLDOC-IGNORE

This comment tells shelldocs that this file should not be processed.

Avoiding Private or Non-Replaceable Functions

Some functions are not meant to be used by 3rd parties or cannot be easily replaced. These functions may be omitted from the documentation by using the --skipprnorep flag:

$ shelldocs --skipprnorep --input directory --output file.md

Lint Mode

In order to ensure minimal documentation, shelldocs has a --lint mode that will point out functions that are missing required annotations:

$ shelldocs --input directory --lint

This will process directory and inform the user of any such problems.