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

【问题标题】：How to documenting global dependencies for functions?如何记录函数的全局依赖关系？
【发布时间】：2010-05-06 17:58:31
【问题描述】：

我从第 3 方供应商（用于嵌入式平台）处获得了一些使用全局变量（用于速度和空间优化）的 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 cmets，该函数依赖于全局变量data_buffer。

【问题讨论】：

标签： c documentation global-variables doxygen

【解决方案1】：

您可以为此添加注释并使用\link 指令将读者引导至全局变量的描述。

【讨论】：

【解决方案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
}

【讨论】：