shelldocs

• Purpose
• Requirements
• Function Annotations
  • Audience / Stability
  • Multiple Parameters
  • Return Values
  • Code Example
• Basic Usage
• Skipping Files
• Avoiding Private or Non-Replaceable Functions
• Lint Mode

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

• Python 2.7

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.