documentation - 在 Doxygen 中，如何通过示例代码中的函数名称而不是标签来包含片段

Question

我知道如何通过标记示例文件的一部分来创建片段:

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

然后在其他地方包括:

/snippet mytestfile.c myfunc example

就我而言，我的示例文件是我的测试文件，每个示例实际上已经在一个函数中，如下所示:

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

所以我想要的是能够引用这样的片段:

/snippet mytestfile.c#testMyFunc

这样我就不必添加额外的标记。你会认为因为 Doxygen 已经解析了代码，所以我可以引用特定的函数来包含。

Answer 1

我还没有找到任何官方解决方案，但我已经为我制作了一个脚本。
希望这对你有用，这是一个例子。

项目结构

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

生成文档

我从我的项目的根目录运行它以生成带有 auto-snippet 的文档: cd ./doc && ./generate_doc.sh
在我的 ./doc/doxygen.conf 我已经设置了这个:

EXAMPLE_PATH           = ../test/snippet/

脚本

./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

细节

使用 ./src/api.h 中的片段你只需添加这一行:@snippet test_api.c name_of_your_function

我所有的测试函数都返回 void , 如果不是你的情况，你必须调整这个 expr "$line" : "^void \?\(.*\?\)(.*\?)" .