Используя Doxygen с C, Вы комментируете прототипа функции или определение? Или оба?

Для общедоступных API я документирую в декларации, так как именно сюда пользователь обычно смотрит первым, если не использует вывод doxygen.

У меня никогда не было проблем с документированием только в одном месте, но я использовал его с C ++; может быть иначе с C, хотя я в этом сомневаюсь.

[править] Никогда не пишите дважды. Никогда. Документация в исходном коде также следует за DRY, особенно в отношении подобных извращений копирования и вставки. [/ Edit]

Однако вы можете указать, хотите ли вы предупреждений для недокументированных элементов . Хотя такие предупреждения теоретически выглядят хорошо, мой опыт показывает, что они быстро становятся скорее обузой, чем помощью. Документирование всех функций обычно не подходит (бывает, что это избыточная документация или даже мешающая документация, и особенно слишком много документации); Для хорошей документации нужен знающий человек, проводящий с ней время. Учитывая это, в этих предупреждениях нет необходимости.

И если у вас нет ресурсов для написания хорошей документации (деньги, время, что угодно ...), то эти предупреждения тоже не помогут.

Я часто использую Doxygen с C для встроенных систем. Я стараюсь писать документацию для любого отдельного объекта только в одном месте, потому что дублирование приведет к путанице позже. Doxygen выполняет некоторое слияние документов, поэтому в принципе можно задокументировать общедоступный API в файле .h , а некоторые заметки о том, как он на самом деле работает, добавлены в . c файл. Я сам пытался этого не делать.

Если перемещение документов из одного места в другое изменяет количество выдаваемых предупреждений, это может быть намеком на то, что между объявлением и определением может быть что-то неуловимое. Компилируется ли код, например, с -Wall -Wextra? Существуют ли макросы, которые изменяют код в одном месте, а не в другом? Конечно, Doxygen '

Мы комментируем только определения функций, но мы используем их с C ++.
Писать это в обоих местах - пустая трата времени. Что касается предупреждения, если ваша документация выглядит хорошо, возможно, это хороший способ игнорировать такие предупреждения.

Цитата из моего ответа на этот вопрос: Документация по заголовочному файлу C / C ++ :

Я поместил документацию по интерфейсу (параметры, возвращаемое значение, что функция выполняет) в файле интерфейса (.h), а также документацию для реализация ( как функция делает) в файле реализации (.c, .cpp, .m). Я пишу обзор class непосредственно перед его объявлением, поэтому читатель сразу получает базовый информации.

В Doxygen это означает, что документация с описанием обзора, параметров и возвращаемых значений ( \ short , \ param , \ return ) используется для документирование прототипа функции и встроенная документация ( \ details ) используется для документирования тела функции (вы также можете обратиться к моему ответу на этот вопрос: Как получить возможность извлекать комментарии изнутри функции в doxygen ? )