In Doxygen, how to include snippet by function name from sample code instead of tag
I know how to create a snippet by marking the section of the example file:
//! [myfunc example]
int i = myfunc(1,"example");
if (i = CORRECT_VALUE) printf("success");
//! [myfunc example]
and then including elsewhere:
/snippet mytestfile.c myfunc example
In my case, my example files are my test files, and each example is actually already in a function, for example:
void testMyFunc() {
int i = myfunc(1,"example");
if (i = CORRECT_VALUE) printf("success");
}
So, I want to be able to reference a fragment like this:
/snippet mytestfile.c#testMyFunc
and that way I wouldn't have to add any additional markup. You might think that since Doxygen has already parsed the code, I might be referring to certain functions to include.
source to share
I didn't find an official solution, but I made a script that did it for me.
Saying that it might be helpful to you is an example.
Project structure
doc/
- doxygen.conf
- generate_doc.sh
- generate_snippet.sh
src/
- api.h
- api.c
test/
- test_api.c
Generating a document
I run this from the root of my project to create an auto-snippet document: cd ./doc && ./generate_doc.sh
In mine, I installed this: ./doc/doxygen.conf
EXAMPLE_PATH = ../test/snippet/
Scripts
./doc/generate_doc.sh
#!/bin/bash
# ./doc/generate_doc.sh
rm ../test/snippet/* # Clean old snippet
for file in ../test/*
do
if [ -f $file ]; then
./generate_snippet.sh ../test/$file # Auto-generate snippet for this file
fi
done
doxygen doxygen.conf # Generate documentation
exit $?
./doc/generate_snippet.sh
#!/bin/bash
# ./doc/generate_snippet.sh
CURRENT_FUNCTION_NAME=""
N_OPEN=0
SNIPPING=0
TARGET="snippet/""`basename "$1"`"
cd "`dirname "$1"`"
mkdir -p snippet
touch "$TARGET"
while IFS='' read -r line || [[ -n "$line" ]]; do
if [ $SNIPPING -eq 0 ]; then
if [ "`echo "$line" | grep -E "^void\ ?\*?.*?\)"`" != "" ]; then
# Found a function
SNIPPING=1
CURRENT_FUNCTION_NAME="`expr "$line" : "^void \?\(.*\?\)(.*\?)"`"
echo "//! [$CURRENT_FUNCTION_NAME]" >> "$TARGET"
fi
fi;
countopen=${line//[^\{]/}
countclose=${line//[^\}]/}
if [[ "$line" == *"{"* ]]; then
let "N_OPEN+=${#countopen}" # Add number of open
fi
if [[ "$line" == *"}"* ]]; then
let "N_OPEN-=${#countclose}" # Add number of close
fi
echo "$line" >> "$TARGET"
if [ $N_OPEN -eq 0 ] && [ $SNIPPING -eq 1 ]; then
echo "//! [$CURRENT_FUNCTION_NAME]" >> "$TARGET"
SNIPPING=0
fi
done < "$1"
exit 0
More details
- To use the snippet in
./src/api.h
, you should simply add this line:@snippet test_api.c name_of_your_function
- All my test functions return
void
, if this is not your case, you should adapt this oneexpr "$line" : "^void \?\(.*\?\)(.*\?)"
.
source to share