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
Posted by at

9 comments:

  1. AnonymousApril 3, 2012 at 4:31 PM

    Thanks a lot dude! Just enough to get there!

    ReplyDelete
  2. UnknownOctober 9, 2013 at 3:46 AM

    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. chieflbmOctober 31, 2013 at 10:46 AM

    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. Ein BlogNovember 11, 2014 at 5:43 PM

    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. UnknownMay 9, 2015 at 4:20 PM

    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. AnonymousMay 20, 2015 at 6:42 AM

    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. UnknownJuly 8, 2015 at 4:40 PM

    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. mikOctober 6, 2018 at 1:49 AM

    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
  9. AnonymousSeptember 15, 2024 at 6:35 AM

    Respect and I have a nifty proposal: Whole Home Renovation Cost 1970's split level remodel

    ReplyDelete

Subscribe to: Post Comments (Atom)