Como documentar minhas funções e aliases personalizados do bash?

Question

Problema:

Eu tenho várias funções e aliases bash. Não consigo me lembrar de todas elas, então geralmente acabo abrindo meus arquivos .bash_functions e .bash_aliases para encontrar o que preciso.

Pergunta (s):

Como posso listar funções / aliases disponíveis no prompt do bash?

É possível eu documentar minhas funções / aliases bash usando comentários (como o PHPDoc)?

Gostaria apenas de uma maneira simples / bacana de mostrar o que está disponível sem ter que abrir os arquivos. Seria legal executar um comando e tê-lo cuspido em uma lista dinâmica de minhas funções / aliases (exemplos de uso seriam um plus). :)

    

Answer 1

Para listar aliases ativos, execute:

alias

Para ver os nomes de todas as funções ativas, execute:

declare -F

Para ver os nomes e definições de todas as funções ativas, execute:

declare -f

Mais

As informações sobre os aliases também estão disponíveis em um formato amigável ao script com:

declare -p BASH_ALIASES

man bash fornece mais informações sobre o 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.

Em relação às funções, man bash explica que declare pode fornecer ainda mais informações disponíveis se a opção extdebug estiver definida:

   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. link
2. link

Answer 2

Eu uso a seguinte função e os comentários do javadoc para criar uma opção --help para meus 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 \([^}]*\)}\(.*\)$/\
            \"\\E[32;40m\\E[37;40m\t(value: \"$\")\"/');
    else
        # other color commands
        echo -e $(echo ${line} | sed \
            -e 's/{@code \([^}]*\)}/\E[36;40m\E[37;40m/g');
    fi
done;
}

No link , você pode ver como é usado dentro de um script real.