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