Как документировать глобальные зависимости для функций?

У меня есть код C от стороннего поставщика (для встроенной платформы), который использует глобальные переменные (для оптимизации скорости и пространства). Я документирую код, конвертирую в формат Doxygen.

Как добавить в документацию к функции примечание, которое требуется функции для глобальных переменных и функций?

Doxygen имеет специальные команды для аннотирования параметров и возвращаемых значений, как описано здесь: Специальные команды Doxygen. Я не видел никаких команд для глобальных переменных.

Пример кода 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.


c global-variables documentation doxygen
person Thomas Matthews    schedule 06.05.2010    source источник

Ответы (2)


arrow_upward
0
arrow_downward

Вы можете просто добавить примечание на этот счет и использовать директиву \link, чтобы направить читателя к описанию глобальной переменной.

person Judge Maygarden    schedule 06.05.2010

arrow_upward
0
arrow_downward

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
}
person user3799415    schedule 05.02.2015