Search This Blog

Loading...

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

7 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