How to document my custom bash functions and aliases?

Question

Problem:

I have multiple bash functions and aliases. I can't remember all of them off the top of my head, so I usually end up opening my .bash_functions and .bash_aliases files to find what I need.

Question(s):

How can I list functions/aliases available from the bash prompt?

Is it possible for me to document my bash functions/aliases using comments (kinda like PHPDoc)?

I'd just like a simple/nice way to output what's available without having to open the files. It would be cool to run a command and have it spit out a dynamic list of my functions/aliases (usage examples would be a plus). :)

Answer 1

To list active aliases, run:

alias

To see names of all active functions, run:

declare -F

To see the names and definitions of all active functions, run:

declare -f

More

The information on aliases is also available is a script-friendly format with:

declare -p BASH_ALIASES

man bash provides more info on the alias builtin:

   alias [-p] [name[=value] ...]
          Alias with  no  arguments  or  with  the  -p
          option  prints  the  list  of aliases in the
          form alias name=value  on  standard  output.
          When  arguments  are  supplied,  an alias is
          defined for each name whose value is  given.
          A  trailing  space in  value causes the next
          word to be checked  for  alias  substitution
          when  the  alias is expanded.  For each name
          in the argument list for which no  value  is
          supplied, the name and value of the alias is
          printed.  Alias returns true unless  a  name
          is   given  for  which  no  alias  has  been
          defined.

Regarding functions, man bash explains that declare can provide still more information is available if the extdebug option is set:

   Function  names  and definitions may be listed with
   the -f option to the  declare  or  typeset  builtin
   commands.  The -F option to declare or typeset will
   list the function names only  (and  optionally  the
   source  file and line number, if the extdebug shell
   option is enabled).

Links

1. http://ss64.com/bash/alias.html
2. http://linfo.org/alias.html

Answer 2

I use the following function and javadoc like comments to create a --help option for my scripts:

PROG=$0 #The program name, used within doHelp

# Print a help message
# doHelp uses lines starting with ## to create the output
# the tags {@param ...} and {@code ...} colorize words
doHelp() {
grep '^##' "${PROG}" |
sed -e 's/^##[[:space:]]*//' |
while read line; do
    if ( echo "${line}" | grep -q '{@param [^}]*}' ); then
        # color parameter and echo evaulated value
        eval echo -e $(echo ${line} | sed \
            -e 's/^\(.*\){@param \([^}]*\)}\(.*\)$/\
            \"\1\\\\E[32;40m\2\\\\E[37;40m\\t(value: \"$\2\")\3\"/');
    else
        # other color commands
        echo -e $(echo ${line} | sed \
            -e 's/{@code \([^}]*\)}/\\E[36;40m\1\\E[37;40m/g');
    fi
done;
}

At https://github.com/kaspervandenberg/aida/blob/master/Search/zylabPatisClient/src/main/scripts/generateReport.sh you can see how it's used within an actual script.

Answer 3

I have been self-documenting bash functions in my ~./bashrc with the : (null) built-in. The benefit is that it won't execute anything when run, but will show when printed.

$ declare -f my_function
my_function() {
    : My function does this and that
    echo "foo"
}
$ my_function
foo