如何記錄函數的全局依賴關係？

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 
}