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

Question

Я получил код 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.

Answer 1

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
}

Answer 2

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