Где поставить Doxygen комментарий блоки для внутренней библиотеки - в Н или в CPP файлы?

голоса
83

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

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

Плюсы:

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

Минусы:

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

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

Задан 10/12/2008 в 11:23
источник пользователем
На других языках...                            


8 ответов

голоса
66

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

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

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

Ответил 15/01/2009 в 00:18
источник пользователем

голоса
50

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

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

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

Например:

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;
}
Ответил 12/10/2011 в 09:23
источник пользователем

голоса
14

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

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

Ответил 09/01/2009 в 15:22
источник пользователем

голоса
9

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

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

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

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

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

Ответил 10/12/2008 в 11:39
источник пользователем

голоса
3

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

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

Ответил 08/01/2009 в 11:29
источник пользователем

голоса
3

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

Ответил 05/01/2009 в 16:06
источник пользователем

голоса
2

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

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

Ответил 24/09/2012 в 21:34
источник пользователем

голоса
0

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

Ответил 15/11/2013 в 21:06
источник пользователем

Cookies help us deliver our services. By using our services, you agree to our use of cookies. Learn more