anvil / bash-doxygen Goto Github PK

A doxygen filter for bash scripts

License: Do What The F*ck You Want To Public License

Shell 22.62% sed 77.38%

doxygen doxygen-filter sed bash

bash-doxygen's Introduction

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

If you do not have a Doxygen configuration file (usually named Doxyfile), you can generate one by simply running doxygen -g.
Edit the Doxyfile to map shell files to C parser: EXTENSION_MAPPING = sh=C
Set your shell script file names pattern as Doxygen inputs, like e.g.: FILE_PATTERNS = *.sh
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 !

bash-doxygen's People

Stargazers

Watchers

bash-doxygen's Issues

Warning arguments not present

test.sh:20: warning: argument 'delimiter' of command @param is not found in the argument list of hello(delimiter)
test.sh:8: warning: argument 'string' of command @param is not found in the argument list of simple_function(string, delimiter)
test.sh:8: warning: argument 'delimiter' of command @param is not found in the argument list of simple_function(string, delimiter)

Since .sh files are based on the C oxygen parser, this error seems logic, but I was wondering if we could prevent it.

Use \syntax instead of @syntax

I was wondering if this was possible to use the regular Doxygen syntax with backslashes (e.g. commands like \brief) instead of the syntax with @ annotations?

Detect functions

Hi.
Great sed job :-)
Anyway, the detection of functions is inconsistent...

bash allows following function definitions:
: funcname() {
: function funcname() {
: function namespace::funcname() {

Is it possible to reflect this in the script?

Can we get Doxygen to complain about undocumented files and methods?

I'd like to have Doxygen complain about undocumented functions. I have the relevant options set in my Doxyfile.

However, the sed script does not generate anything for functions without a @fn directive. So, undocumented functions are completely hidden with no warning.

Could you please add some support for this?

Question about bash function return values

I think that there are two types of return values of shell functions: the exit code and the standard output. The exit code of a function can be checked for errors and the standard output is usually used as values(call by ref).

if number_of_procs=$(nproc); then
# do something with number_of_procs
else
# handle error
fi

Now, let's say nproc is a shell function rather than the binary. How would you document \retval(the standard output - number of threads) and \exitcode(0 on success, 1 on error)?

Build call graph

Hi.

Is there a way to detect function calls in order to build the call graph ?

Not working if the .sh file does not have a @file statement

I followed your instructions properly, but had a hard time figuring out this issue. Is this a regular behavior?

If not, I'm eager to publish a PR.

Also, I have good practise rules to add wrt. \return and \retval usage in bash.

Trying Doxygen on MacOS with the example provided

Hi, I tried to run doxygen for bash on the example provided but the html generated is empty, I am using GNU Sed.

Attached all the below files:

Doxygen output from the console
Doxyfile
Example file : ex.sh
Output html folder

Archive.zip

Cumulus-AT1176:~ ahmed$ /usr/local/bin/sed --version
/usr/local/bin/sed (GNU sed) 4.5
Copyright (C) 2018 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later https://gnu.org/licenses/gpl.html.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Written by Jay Fenlason, Tom Lord, Ken Pizzini,
and Paolo Bonzini.
GNU sed home page: https://www.gnu.org/software/sed/.
General help using GNU software: https://www.gnu.org/gethelp/.
E-mail bug reports to: [email protected].
Cumulus-AT1176:~ ahmed$ uname -a
Darwin Cumulus-AT1176 17.5.0 Darwin Kernel Version 17.5.0: Mon Mar 5 22:24:32 PST 2018; root:xnu-4570.51.1~1/RELEASE_X86_64 x86_64

Combine bash documentation with c++ documentation

I want to combine your nice script in doxygen with my C++ documentation. When I add sed -n -f /path/to/doxygen-bash.sed -- to INPUT_FILTER, it is not showing my CPP classes anymore, but only 'Files'. What to add there so I still have my classes documented?

warning: documented symbol ... was not declared or defined.

#!/bin/bash

## @file      test.sh
## @brief     Simple demo to for debug of bash-doxygen issue
## @author    Eric Butters
## @date      2018-02-07
## @copyright CLOSED
## @details   none

## @fn abc
## @brief echo ABC
function abc() {
   echo "ABC"
}

## @fn def
## @brief echo DEF
function def() {
   echo "DEF"
}

abc
def


# THIS WILL RESULT IN WARNINGS AND NOT CORRECT DOCUMENTATION
# test.sh:10: warning: documented symbol `abc' was not declared or defined.
# test.sh:16: warning: documented symbol `abc' was not declared or defined.

The workaround I have found is to install gnu-sed via homebrew, then use gsed instead of sed in Doxyfile.

Not sure if you want to support both versions of sed, but it might be helpful to others to make note of this workaround in the README.