How to documenting global dependencies for functions?

问题

I've got some C code from a 3rd party vendor (for an embedded platform) that uses global variables (for speed & space optimizations). I'm documenting the code, converting to Doxygen format.

How do I put a note in the function documentation that the function requires on global variables and functions?

Doxygen has special commands for annotating parameters and return values as describe here: Doxygen Special Commands. I did not see any commands for global variables.

Example C code:

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

In the above code, I would like to add Doxygen comments that the function depends on the global variable data_buffer.

回答1:

You can just add a note to that effect and use the \link directive to direct the reader to the description of the global variable.

回答2:

Doxygen could do with an @global command to complement @param. Until that day arrives you could approximate it with aliases.

In your Doxygen configuration file add the following aliases:

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>"

Example of usage:

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
}

来源：https://stackoverflow.com/questions/2783300/how-to-documenting-global-dependencies-for-functions

标签

documentation

global-variables

doxygen