Зачем загромождать хэдеры развёрнутыми комментариями и описаниями, если предполагается получать полную документацию по API простым путём (с помощью doxygen в твоём случае)? ".c/.cpp" однократно распарсятся во время компиляции, на выходе получишь библиотеку и доку по API. А хэдеры остаются неизменными - нафиг их такие громоздкие таскать в комплекте с библиотекой и парсить лишние килобайты какждый раз при сборке с библиотекой?
Я все пишу в одном месте — в .h'никах. Чтобы можно было открыть и сразу понять что к чему. В .cpp файлах комментарии относящиеся к документации обычно не пишую.
> Зачем загромождать хэдеры развёрнутыми комментариями и описаниями, если предполагается получать полную документацию по API простым путём (с помощью doxygen в твоём случае)? ".c/.cpp" однократно распарсятся во время компиляции, на выходе получишь библиотеку и доку по API. А хэдеры остаются неизменными - нафиг их такие громоздкие таскать в комплекте с библиотекой и парсить лишние килобайты какждый раз при сборке с библиотекой?
> Я все пишу в одном месте — в .h'никах. Чтобы можно было открыть и сразу понять что к чему. В .cpp файлах комментарии относящиеся к документации обычно не пишую.
С точки зрения комментариев мне очень понравились «лептоника» и gwyddion: в заголовочных файлах более-менее подробное описание структур, сишные файлы содержат общую информацию в «шапке» и сведения о назначении, аргументах и возвращаемом значении перед каждой функцией.