Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
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:
- Functions SHOULD contain a local
$FUNCDESCvariable that describes the function.
- Only "interactive" functions that would be called from a command-line MUST have a
- 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 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
- Inspired by Bash's
- Shell comments are not tokenised, so printing the function definition with
typewould miss them.
There is a
usage function in 10_meta.sh (self-documented) that can be used to show function usage with parameters. Use that.
There are functions on functions for exploring the code:
fns lists interactive shell functions that have been
With argument "-a" or "--all" list all functions (including those starting with an underscore
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
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.