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

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

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

Плюсы:

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

Минусы:

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

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

Ответы

Ответ 1

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

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

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

Ответ 2

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

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

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

Например:

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 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

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

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

Ответ 4

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

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

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

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

Мой файл1.h

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

MY file1.c

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

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

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

Ответ 5

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

Ответ 6

Я помещаю все в файл заголовка.

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

Ответ 7

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

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

Ответ 8

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