Я использую Doxygen с некоторым встроенным исходным кодом C. Учитывая пару файлов .c/.h, размещаете ли вы комментарии Doxygen в прототипе функции (файл .h) или в определении функции (файл .c) или дублируете их в обоих местах?
У меня проблема, из-за которой Doxygen предупреждает об отсутствии комментариев, когда я документирую в одном месте, но не в другом; это ожидаемо, или мой Doxygen облажался?
Для общедоступных API я документирую в объявлении, так как именно здесь пользователь обычно смотрит в первую очередь, если не использует вывод doxygen.
У меня никогда не было проблем с документированием только в одном месте, но я использовал его с C++; может быть по-другому с C, хотя я сомневаюсь в этом.
[править] Никогда не пишите это дважды. Никогда. Документация в исходном коде также следует DRY, особенно в отношении таких извращений копирования и вставки.
Однако вы можете указать, хотите ли вы получать предупреждения о недокументированных элементах. Хотя в теории такие предупреждения выглядят красиво, мой опыт показывает, что они скорее обременяют, чем помогают. Документирование всех функций обычно не выход (есть такая вещь, как избыточная документация или даже мешающая документация, и особенно слишком много документации); хорошая документация требует, чтобы знающий человек проводил с ней время. Учитывая это, эти предупреждения не нужны.
И если у вас нет ресурсов для написания хорошей документации (денег, времени, чего угодно...), то эти предупреждения тоже не помогут.
Цитата из моего ответа на этот вопрос: документация файла заголовка C/C++:
Я поместил документацию по интерфейсу (параметры, возвращаемое значение, что функция) в файле интерфейса (.h), а документацию по реализации (как функция делает) в файле реализации (.c, .cpp, .m). Я пишу обзор класса непосредственно перед его объявлением, чтобы читатель сразу получил основную информацию.
В Doxygen это означает, что документация, описывающая обзор, параметры и возвращаемые значения (\brief, \param, \return), используется для документирования прототипа функции, а встроенная документация (\details) используется для документирования тела функции (вы также можете обратиться к моему ответу на этот вопрос : Как иметь возможность извлекать комментарии внутри функции в doxygen?)
Я часто использую Doxygen с C для встраиваемых систем. Я стараюсь писать документацию для любого отдельного объекта только в одном месте, потому что дублирование приведет к путанице позже. Doxygen в некоторой степени объединяет документы, так что в принципе можно задокументировать публичный API в файле .h, а некоторые заметки о том, как он на самом деле работает, можно добавить в файл .c. Я сам пытался этого не делать.
Если перемещение документов из одного места в другое изменяет количество выдаваемых предупреждений, это может быть намеком на то, что между объявлением и определением может быть что-то тонкое. Например, компилируется ли код с помощью -Wall -Wextra? Существуют ли макросы, которые изменяют код в одном месте, а не в другом? Конечно, парсер Doxygen не является полноценным парсером языка, и его тоже можно запутать.
Мы комментируем только определения функций, но используем их с C++.
Писать в обоих местах — значит терять время. Что касается предупреждения, если ваша документация выглядит хорошо, возможно, это хороший способ игнорировать такие предупреждения.
Я задал себе тот же вопрос и был приятно удивлен, увидев, что Doxygen фактически включает ту же встроенную документацию, которая находится в файле .c в соответствующем файле .h при просмотре сгенерированной html-документации. Следовательно, вам не нужно повторять встроенную документацию, и Doxygen достаточно умен, чтобы включить ее в оба места!
Я использую версию Doxygen версии 1.8.10.
