In Doxygen how can include a snippet by function name from example code instead of by tag

问题

I know how to create a snippet by marking a section of an example file:

//! [myfunc example]
int i = myfunc(1,"example");
if (i = CORRECT_VALUE) printf("success");
//! [myfunc example]

and then including that elsewhere with:

/snippet mytestfile.c myfunc example

In my case, my example files are my test files, and each example is actually already in a function, like this:

void testMyFunc() {
    int i = myfunc(1,"example");
    if (i = CORRECT_VALUE) printf("success");
}

So what I want, is to be able to refer to the snippet something like this:

/snippet mytestfile.c#testMyFunc

and that way I wouldn't have to add extra markup. You would think that because Doxygen has parsed the code already that I could refer to specific functions for inclusion.

回答1:

I haven't found any official solution but I have made a script that do this for me.
Hopping that this could be useful for you, here is an example.

Project structure

doc/
 - doxygen.conf
 - generate_doc.sh
 - generate_snippet.sh
src/
 - api.h
 - api.c
test/
 - test_api.c

Generating doc

I run this from the root directory of my project to generate doc with auto-snippet :
cd ./doc && ./generate_doc.sh

In my ./doc/doxygen.conf I have set this :

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

Details

To use a snippet in ./src/api.h you've just to add this line :
@snippet test_api.c name_of_your_function
All my test functions return void, if it's not your case you must adapt this expr "$line" : "^void \?$.*\?$(.*\?)".

来源：https://stackoverflow.com/questions/25511878/in-doxygen-how-can-include-a-snippet-by-function-name-from-example-code-instead

标签

documentation

doxygen