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

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

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

Плюсы:

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

Минусы:

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

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

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

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

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

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

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

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

Например:

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

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

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

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

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

Мы просто используем все глобальные функции, прокомментированные в заголовках, и локальные функции, прокомментированные в исходном коде. Если вы хотите, вы также можете включить команду 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*/}

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

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

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

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

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

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

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

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