When I want to have docstrings for my bash functions, I use a solution similar to the suggestion of user12205 in a duplicate of this question.
See how I define USAGE for a solution that:
- auto-formats well for me in my IDE of choice (sublime)
- is multi-line
- can use spaces or tabs as indentation
- preserves indentations within the comment.
function foo {
# Docstring
read -r -d '' USAGE <<' END'
# This method prints foo to the terminal.
#
# Enter `foo -h` to see the docstring.
# It has indentations and multiple lines.
#
# Change the delimiter if you need hashtag for some reason.
# This can include $$ and = and eval, but won't be evaluated
END
if [ "$1" = "-h" ]
then
echo "$USAGE" | cut -d "#" -f 2 | cut -c 2-
return
fi
echo "foo"
}
So foo -h
yields:
This method prints foo to the terminal.
Enter `foo -h` to see the docstring.
It has indentations and multiple lines.
Change the delimiter if you need hashtag for some reason.
This can include $$ and = and eval, but won't be evaluated
Explanation
cut -d "#" -f 2
: Retrieve the second portion of the #
delimited lines. (Think a csv with "#" as the delimiter, empty first column).
cut -c 2-
: Retrieve the 2nd to end character of the resultant string
Also note that if [ "$1" = "-h" ]
evaluates as False
if there is no first argument, w/o error, since it becomes an empty string.