Doxygen:如何仅使用其文档 block 而不是代码来记录非 C 函数？

Question

我希望 Doxygen 记录用类 C 语言 (PARI/GP) 编写但语法略有不同的代码。我相信 Doxygen 可以记录那些不存在的实体。这似乎是完成这项工作的最简单方法，而编程语言不受 Doxygen 支持。我想要这样的东西:

/*!
 \fn foo(param,{option})
 \brief some brief description here
 \param[in](param) mandatory parameter description
 \param[in](option) optional parameter description
*/
/*! \cond DOXYGEN_SHOULD_SKIP_THIS */
foo(param, {option}) =
{
    ...
};
addhelp(foo, "help message for `foo` function");
/*! \endcond */

不幸的是，Doxygen 会生成警告“未声明或定义已记录的符号‘foo’”，并且不会在输出 HTML 中列出 foo。有什么方法可以强制 Doxygen 只使用文档 block 而不是代码来生成正确的 HTML？

Answer 1

有多种选择

1. 您可以编写一个输入过滤器，将您的代码转换成看起来很像 C 的东西，以便 doxygen 对其进行解析(另请参阅 FILTER_PATTERNS 和 EXTENSION_MAPPING)。

2. 您可以创建一个包含函数原型(prototype)的虚拟 C 文件，并将其记录下来。如果您使用问题中提到的方法，您可以将文档放在 C 文件或您的编程语言中。

3. 如果您的语言支持 C 预处理器，您可以使用 doxygen 的 C 预处理器来对 doxygen 隐藏部分文件，即

   #if DOXYGEN_ONLY
   /**
    \brief some brief description here
    \param[in](param) mandatory parameter description
    \param[in](option) optional parameter description
   */
   void foo(param,option);
   #endif
   foo(param, {option}) { ... };
   

   然后在配置文件中定义以下内容:

   PREDEFINED = DOXYGEN_ONLY