Где разместить блоки комментариев doxygen для внутренней библиотеки - в H или в файлах CPP? [закрыто]

98

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

НО ... Я думал о прямо противоположном подходе, когда разрабатываю внутреннюю для компании (или как побочный проект для себя) библиотеку, которая будет использоваться с полным исходным кодом. Я предлагаю поместить большие блоки комментариев в файлы реализаций (HPP, INL, CPP и т.д.), чтобы НЕ загромождать интерфейс классов и функций, объявленных в заголовке.

Плюсы:

  • Меньше беспорядка в файлах заголовков, можно добавить только категоризацию функций.
  • Блоки комментариев, которые предварительно просматриваются при использовании, например, Intellisense, не конфликтуют - это дефект, который я наблюдал, когда у меня есть блок комментариев для функции в файле .H и его встроенное определение находится в том же файле .H но включен из файла .INL.

Минусы:

  • (Очевидное) Блоки комментариев не находятся в файлах заголовков, где находятся объявления.

Итак, что вы думаете и, возможно, предлагаете?

Singulus
источник

Ответы:

77

Разместите документацию там, где люди будут читать и писать, когда они используют и работают над кодом.

Комментарии к классам идут перед классами, комментарии к методам - ​​перед методами.

Это лучший способ убедиться, что все в порядке. Это также сохраняет ваши файлы заголовков относительно компактными и позволяет избежать трогательной проблемы, когда люди обновляют документы методов, что приводит к загрязнению заголовков и запуску перестроек. На самом деле я знаю, что люди используют это как предлог для написания документации позже!

Энди Дент
источник
11
У меня было болезненное напоминание о том, почему следует избегать документов в заголовках - старший вице-президент посоветовал мне помещать комментарии к методам в объявление класса, и я обнаружил, что на самом деле сохраняю изменения комментариев на потом, потому что нажатие этих заголовков запускает 45-минутное время сборки !
Энди Дент
7
Не голосование против, а просто вопрос: если я пытаюсь выяснить, что делает API (даже внутренний), я бы предпочел не открывать .cpp и пробираться через весь код, чтобы найти документацию. Я признаю, что было бы неприятно, если бы вы документировали больше, чем просто мнение клиента о том, что делает метод (например, как он это делает), но вы все равно не должны этого делать, верно?
TED
8
Весь смысл использования Doxygen для создания вашей документации состоит в том, чтобы иметь доступ к созданной документации. У нас есть внутренний веб-сервер, на который идет вывод Doxygen, и мы можем затем использовать ссылки на страницы этого сервера в обсуждениях. Это также связывает воедино документацию по классам или методам с дополнительными страницами, на которых обсуждаются более широкие вопросы проектирования.
Энди Дент
1
Решение, насколько публичным должно быть обсуждение реализации, - интересный вопрос. Конечно, если есть определенный алгоритм или побочные эффекты, я бы предпочел знать о них как о клиенте библиотеки. Иногда это должен знать только сопровождающий, а в Doxygen есть простой способ пометить условные разделы, чтобы вы могли создавать разные документы для разных точек зрения.
Энди Дент
77

Мне нравится использовать тот факт, что имена могут быть задокументированы в нескольких местах.

В заголовочном файле я пишу краткое описание метода и документирую все его параметры - они менее вероятно изменятся, чем реализация самого метода, а если они изменятся, то прототип функции нужно изменить в любом случае .

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

Например:

mymodule.h

/// @brief This method adds two integers.
/// @param a First integer to add.
/// @param b Second integer to add.
/// @return The sum of both parameters.
int add(int a, int b);

mymodule.cpp

/// This method uses a little-known variant of integer addition known as
/// Sophocles' Scissors. It optimises the function's performance on many
/// platforms that we may or may not choose to target in the future.
/// @TODO make sure I implemented the algorithm correctly with some unit tests.
int add(int a, int b) {
  return b + a;
}
Дэниел Бакмастер
источник
3
Мне нравится этот метод, но он несовместим с AUTOBRIEF. Мне было бы интересно узнать, есть ли обходной путь конфигурации для устранения множества создаваемых сводок.
Аарон Райт
Мне тоже нравится этот метод, он дает хороший баланс в реализации.
Xofo
Я не могу воспроизвести этот метод на своей машине с помощью Doxygen 1.8.15. Документация по параметрам не отображается, только краткие и подробные описания.
punyidea
1
Приложение: изменение размещения подробного описания внутри блока функции сделало эту работу для меня. Описание теперь добавляется в конец описаний в заголовочных документах.
punyidea
19

Наличие комментариев в заголовке означает, что все пользователи класса должны быть перекомпилированы, если комментарий изменен. Для больших проектов кодеры будут менее склонны обновлять комментарии в заголовках, если они рискнут потратить следующие 20 минут на восстановление всего.

И ... поскольку предполагается, что вы должны читать html-документ, а не просматривать код в поисках документации, нет большой проблемы в том, что блоки комментариев труднее найти в исходных файлах.


источник
Правильно, но это большая проблема, если это динамическая библиотека, полученная из артефакта, и у вас нет исходных файлов :-)
DrumM
13

Заголовки: легче читать комментарии, поскольку при просмотре файлов меньше «шума».

Источник: тогда у вас есть фактические функции, доступные для чтения, просматривая комментарии.

Мы просто используем все глобальные функции, прокомментированные в заголовках, и локальные функции, прокомментированные в исходном коде. Если вы хотите, вы также можете включить команду copydoc для вставки документации в нескольких местах без необходимости писать ее несколько раз (лучше для обслуживания)

Однако вы также можете скопировать результаты в другую файловую документацию с помощью простой команды. Например: -

Мой файл1.h

/**
 * \brief Short about function
 *
 * More about function
 */
WORD my_fync1(BYTE*);

МОЙ file1.c

/** \copydoc my_func1 */
WORD my_fync1(BYTE* data){/*code*/}

Теперь вы получаете одинаковую документацию по обеим функциям.

Это дает вам меньше шума в файлах кода, в то же время вы получаете документацию, написанную в одном месте, представленную в нескольких местах в конечном результате.

eaanon01
источник
2
когда копируется блок?
Мерт Джан Эргюн
2

Обычно я помещаю документацию для интерфейса (\ param, \ return) в файл .h, а документацию по реализации (\ details) в файл .c / .cpp / .m. Doxygen группирует все в документации по функциям / методам.

Mouviciel
источник
2

Все помещаю в заголовочный файл.

Я все документирую, но только обычно извлекаю публичный интерфейс.

graham.reeds
источник
2

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

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

Sinclair
источник
-1

В C ++ иногда реализация может быть разделена между модулями header и .cpp. Здесь кажется более понятным помещать документацию в файл заголовка, поскольку это единственное место, где гарантируются все общедоступные функции и методы.

кельвин
источник