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

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

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

Плюсы:

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

Минусы:

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

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

10.12.2008 10:23:42
8 ОТВЕТОВ
РЕШЕНИЕ

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

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

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

76
14.01.2009 23:18:26
У меня было болезненное напоминание о том, почему следует избегать использования документов в заголовках - старший вице-президент сказал, что нужно помещать комментарии метода в объявление класса, и обнаружил, что я на самом деле сохраняю редактирование комментариев на потом, потому что нажатие на эти заголовки вызывает 45-минутное время сборки. !
Andy Dent 30.09.2010 00:19:48
Не голосование, просто вопрос: если я пытаюсь понять, что делает API (даже внутренний), я бы предпочел не открывать .cpp и просматривать весь код, чтобы найти документацию. Я признаю, что было бы больно, если вы документируете больше, чем просто представление клиента о том, что делает метод (например, как он это делает), но вы все равно не должны этого делать, верно?
T.E.D. 8.02.2011 14:14:38
Весь смысл использования Doxygen для создания вашей документации состоит в том, чтобы сгенерированная документация была доступна. У нас есть внутренний веб-сервер, на котором идет вывод Doxygen, и мы можем использовать ссылки на страницы на этом сервере в обсуждениях. Это также связывает воедино документацию класса или метода с дополнительными страницами, на которых обсуждаются более широкие вопросы проектирования.
Andy Dent 11.02.2011 14:01:44
Решение о том, насколько публичным должно быть обсуждение реализации, является интересным вопросом. Конечно, если есть определенный алгоритм или побочные эффекты, я бы предпочел узнать о них как о клиенте библиотеки. Иногда об этом должен знать только сопровождающий, и у Doxygen есть простой способ пометить условные разделы, поэтому вы можете создавать разные документы для разных точек зрения.
Andy Dent 11.02.2011 14:06:07

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

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

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

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

Мой file1.h

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

МОЙ file1.c

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

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

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

12
4.12.2013 18:25:56
когда блок копируется?
Mert Can Ergün 2.05.2017 13:38:50

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

2
5.01.2009 15:06:51

Я положил все в заголовочный файл.

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

2
8.01.2009 10:29:14

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

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

17
9.01.2009 14:22:33
Правильно, но это большая проблема, если это динамическая библиотека, полученная из артефакта, и у вас нет исходных файлов :-)
DrumM 20.12.2018 16:08:03

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

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

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

Например:

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;
}
72
27.10.2013 05:48:02
Мне нравится этот метод, но он кажется несовместимым с AUTOBRIEF. Мне было бы интересно узнать, есть ли обходной путь конфигурации для устранения нескольких кратких сводок, которые создаются.
Aaron Wright 16.07.2018 18:36:23
Мне также нравится этот метод, он обеспечивает хороший баланс в реализации.
Xofo 4.09.2018 21:23:21
Я не могу воспроизвести этот метод на своей машине, используя Doxygen 1.8.15. Документация по параметрам не появляется, только краткие и подробные описания.
punyidea 8.04.2019 19:35:36
Приложение: Изменение размещения подробного описания внутри блока функции сделало эту работу для меня. Описание теперь добавляется в конец описания в заголовке документа.
punyidea 8.04.2019 19:48:38

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

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

1
25.09.2012 14:06:34

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

-1
15.11.2013 20:06:15