如何记录函数的全局依赖关系？

Question

我从第三方供应商（针对嵌入式平台）获得了一些使用全局变量（用于速度和空间优化）的C代码。我正在记录代码，转换为Doxygen格式。

如何在功能文档中添加注释，该函数需要全局变量和函数？

Doxygen具有用于注释参数和返回值的特殊命令，如下所述：Doxygen Special Commands。我没有看到任何全局变量的命令。

示例C代码：

    extern unsigned char data_buffer[]; //!< Global variable.

    /*! Returns the next available data byte.
     *  \return Next data byte.
     */
    unsigned char Get_Byte(void)
    {
      static unsigned int index = 0;
      return data_buffer[index++]; //!< Uses global variable.   
    }

在上面的代码中，我想添加Doxygen注释，该函数依赖于全局变量data_buffer。

Answer 1

您只需为该效果添加注释，并使用\link指令将读者引导至全局变量的描述。

Answer 2

Doxygen可以用@global命令来补充@param。直到那一天到来，你可以用别名来近似它。

在Doxygen配置文件中添加以下别名：

ALIASES += global_START="<dl class=\"params\"><dt>Globals</dt><dd><table class=\"params\">"
ALIASES += global_{2}="<tr><td class=\"paramname\">\1</td><td>: \2</td></tr>"
ALIASES += global_END="</table></dd></dl>"

用法示例：

int fxnMAIN_Main(void)
{
  /**
   *   @brief   Bla Bla Bla.
   * 
   *   @global_START
   *   @global_{bExampleOne, Description Here}
   *   @global_{bExampleTwo, Second Description Here}
   *   @global_END
   *
   *   @retval  int :  Bla Bla Bla.
   */

  // Code Here
}