awmyhr / bash-doxygen

A doxygen filter for bash scripts

bash-doxygen

A basic doxygen filter (originally written in GNU sed) allowing you to add inline-documentation to your bash shell scripts.

Supported shell syntaxes

• All lines starting with a ## (without any leading blanks) are passed to doxygen. You can use all the doxygen commands you want in those lines. (see doxygen documentation).

• Some top level declarations will be recognized if you use the declare primitive:

  • declare -a for arrays
  • declare -A for associative arrays
  • declare -i for integers
  • Any other top-level declare statement will consider variable is a string.
  • Those additional declaration attributes can be combined with -A/-a/-i/:
    • declare -l will mark the variable as LowerCase
    • declare -u will mark the variable as UpperCase
    • declare -x will mark the variable as Exported
    • declare -r will mark the variable as ReadOnly
  • Additionally, declaring a variable with an export statement will also be recognized and the variable will be marked as an Exported String.

• Functions declaration will be recognized if all these conditions are met:

  1. a ## @fn line is found above the function declaration,
  2. the function is declared either with or without the non-posix function keyword, but always with ().
  3. the body-opening { char is on the same line as the funcname() instruction.

How to use it

1. If you do not have a Doxygen configuration file (usually named Doxyfile), you can generate one by simply running doxygen -g.
2. Edit the Doxyfile to map shell files to C parser: EXTENSION_MAPPING = sh=C
3. Set your shell script file names pattern as Doxygen inputs, like e.g.: FILE_PATTERNS = *.sh
4. Mention doxygen-bash.sed in either the INTPUT_FILTER or the FILTER_PATTERN directive of your Doxyfile. If doxygen-bash.sed is in your $PATH, then you can just invoke it as is, else use sed -n -f /path/to/doxygen-bash.sed --.

CAREFUL: If you are a BSD and or a Mac user, you will definitely want to use gsed instead of sed to make it work.

Known limitations

Yes.

FAQ

Q. Does it actually work ? A. The bash-argsparse project uses this filter. Check the result. Click on the links. See by yourself.

Q. Is it rock-solid ? A. No.

Q. Do you accept patches ? A. Definitely.

Q. Why is the project named bash-doxygen while the filter is named doxygen-bash ? A. Yeah, haha. Seriously.

Q. Can I include the doxygen-bash.sed file in my own tarball ? A. See the COPYING file.

Q. Dude. sed ? Seriously ? A. Are you.. Jealous ?

Q. ... ? A. Don't you dare !