Мусор в исходниках библиотек, зачем? Опции

[Леонид Иванович]

Для чего в файлах исходников библиотек текст программы перемежается с мусором типа этого (файл CMSIS system_stm32f4xx.h)?

Код

/**
  * @}
  */

/** @addtogroup STM32F4xx_System_Exported_Constants
  * @{
  */

/**
  * @}
  */

/** @addtogroup STM32F4xx_System_Exported_Macros
  * @{
  */

/**
  * @}
  */

/** @addtogroup STM32F4xx_System_Exported_Functions
  * @{
  */

[ViKo]

doxygen

[Леонид Иванович]

Понятно, спасибо. Мешает читабельности.

[ViKo]

Понятно, спасибо. Мешает читабельности.

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

Код

/*!***************************************************************************
@brief        Number to Time
@details    Преобразовать число во время
@param        Num - число
@param        *pBuf - указатель на буфер результата (9 символов + \0)
@note        
*/

Мне нравится. В Notepad++ такие комментарии можно выделять своим стилем. В Keil тоже.
Сам doxygen запускаю редко. В конце работы с проектом. В-основном, чтобы убедиться, что все документировано, хотя бы минимально.
И файлы я предваряю подобными комментариями.