anvil / bash-doxygen Goto Github PK

I want to use intendend @var statements inside my function bodies. If I managed to understand the sed rules correctly, bash-doxygen ignores everything that is intended. If this is the case, it would be great to also pass this info to doxygen.

Fedora 21 provides doxygen-1.8.9.1-2.fc21.x86_64 and bash-argsparse package actually have no documentation in it.

It means either the filter does not work with new doxygen, or that doxygen configuration needs to be additionnally tweaked to make it work. So I need to fix either the code or a documentation.

Tested on OSX 10.11.6.

Functions are not detected correctly on Mac OSX. This is because OSX uses BSD sed. This will probably affect BSD OSes also, considering this. To reproduce, just run the unit test on a mac.

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.

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?

Hi.

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

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?

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.

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)?

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:

1. Doxygen output from the console
2. Doxyfile
3. Example file : ex.sh
4. 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

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.

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?

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?