Self documenting functions

Self documenting shell functions

This idea came from languages like Java and particularly Python and Emacs Lisp: It should be possible to query the system to learn how to use functions, what arguments they expect and what they return.

To this end there are a few conventions used:

Coding conventions

• Functions SHOULD contain a local $FUNCDESC variable that describes the function.
• Only "interactive" functions that would be called from a command-line MUST have a $FUNCDESC
• See below for more on this variable.
• Bash readline completion function names MUST start with one (1) underscore: _
• Functions not intended to be called interactively MUST start with two (2) underscores: __

The $FUNCDESC variable

• The comment SHOULD begin with a single-line sentence that describes the function's purpose or action.
• Following the single descriptive sentence, the rest of the string MAY list details of any parameters or special pre-post conditions.
• The focus in this description SHOULD be on what and why, not how

Why a $FUNCDESC variable?

• Inspired by Bash's $FUNCNAME
• Shell comments are not tokenised, so printing the function definition with type would miss them.

Function usage

There is a usage function in 10_meta.sh (self-documented) that can be used to show function usage with parameters. Use that.

Meta-functions

There are functions on functions for exploring the code:

functions

alias: fns lists interactive shell functions that have been sourced.

With argument "-a" or "--all" list all functions (including those starting with an underscore _)

describe

The describe function in 10_meta.sh will print the first line of any $FUNCDESC that the function contains. It also tells you which file the function was sourced from.

list

The list function (inspired by LIST from BASIC) is like describe but it also shows the in-memory representation of the function, after it was sourced from the file.