Search This Blog

Monday, August 29, 2011

HowTo: Have Doxygen support Bash/Awk/Sed Script files.

OSDir.com - text.doxygen.general - Re: Having Doxygen support script languages - msg#00027

Doxygen doesn't support bash script files. While that probably makes sense, to not support them (define a bash script file in terms of functions and variables), there are always a few laying around in a source tree that should go into the document.

It's easiest to add the script files without changing them, so a doxygen input filter. Input filters work pretty good with command line sed or awk commands, so we'll do a simple one here that lets you add Doxygen commands comeent lines starting with ##.

Edit these lines in your Doxyfile:
FILE_PATTERNS = *.sh *.awk
INPUT_FILTER = "sed -e 's|##|//!|'"
FILTER_SOURCE_FILES = YES

Add a brief description to the top of each file:
## functions for OpenEmbedded, and Jenkins -*- shell-script -*-.
## @author rickfoosusa
## @file

Generally anything with # for a comment will work, but for languages you get a lot more documentation by using a filter like asm4doxy.pl http://rudy.mif.pg.gda.pl/~bogdro/inne/asm4doxy.txt

8 comments:

  1. Thanks a lot dude! Just enough to get there!

    ReplyDelete
  2. Hey,
    first thanks a lot, the following little adds completeness of code-display:
    INPUT_FILTER = "sed -e 's|##\(.*\)$|##\1 //!\1|'"

    Arno-Can Uestuensoez

    ReplyDelete
  3. I am having trouble with Doxygen parsing a bash script. I have a few assigns at the top, like x=1 then y=1 ... it can't parse out y as a separate variable. Is there something I am missing in my config? or is there some doxygen comment to add?

    ReplyDelete
  4. That's a great lead to adapt any kind of files being documented using Doxygen. I've been using your code to create an answer at StackOverflow regarding documentation of makefile templates/snippets: http://stackoverflow.com/questions/26874238/can-doxygen-be-used-to-document-makefile-templates-and-include-mk-file-interfa

    ReplyDelete
  5. Thanks for your valuable hints.

    I'm working with: Doxyfile 1.8.9.1 and i needed to set:

    - EXTENSION_MAPPING = sh=C++

    too to get it producing comments.

    ReplyDelete
  6. For the record, I'm maintaining a more complex doxygen filter for bash scripts. Don't hesitate to fill bug reports or feature request if you feel like to : https://github.com/Anvil/bash-doxygen/

    ReplyDelete
  7. Looks good. I'm looking to document some (sets of) awk scripts, and this might work for me, too. While awk does have a "function" keyword to help identify them, initially I might just filter that keyword out. Not sure what to do with the "pattern recognition" rules yet. They are sort of like a chain of ifs or generalized switch/case selected by data record content. Has anyone else done awk script documentation with doxygen? I like the idea of using and adapting standard open source tools whenever possible.

    ReplyDelete
  8. White listing Doxygen lines with grep is an effective workaround. It keeps only lines starting with #///

    - EXTENSION_MAPPING = sh=C++
    - FILTER_PATTERNS = "*.sh=\"grep ^#///\""

    There is no source parsing possible and all formating has to be done with Doxygen syntax.

    An improvment would be to replace filtered lines with empty lines instead of removing them. Doxygen provides source line references in its documentation

    ReplyDelete