[Turgenev 1]

Есть код на С с файлами реализации - *.с и с заголовочными файлами *.h. Функции задокументированы в файлах реализации и с этим нет проблем. Декларация функций сделана в заголовочных файлах и не задокументирована никак. Но при генерировании выходной документации Doxygen засовывает комментарии и в файл реализации и в заголовочный файл. То есть по сути дублирует описание функции, а оно мне в заголовочном файле не надо, я не документировал декларацию функции.

По идее должно было помочь включение параметра HIDE_UNDOC_MEMBERS: 

Спойлер

Но не помогло совсем. 

Притом Doxygen засовывает в описание заголовочного файла еще и весь листинг кода. Как это отключить не нашел в гугле.

[EdgeAligned 53]

[Turgenev 1]

Удалил *.h, но не помогло. Так же все подряд идет в описании хидер файлов.

[EdgeAligned 53]

Чтобы убрать включение исходных текстов, нужно на вкладке Source Brouser убрать все галочки в списке.
А если на вкладке Input в списке File Patterns удалить *.h, то файлы .h вообще будут убраны из списка файлов.

Вообще, доксиген больше оптимизирован под C++

[Turgenev 1]

14 часов назад, EdgeAligned сказал:

Чтобы убрать включение исходных текстов, нужно на вкладке Source Brouser убрать все галочки в списке.
А если на вкладке Input в списке File Patterns удалить *.h, то файлы .h вообще будут убраны из списка файлов.

С кодом отработало, спасибо. Про File Patterns, когда прочитал, тоже так подумал, но нет, Doxygen все равно- все хидеры так же отображаются в выходной документации.

[Turgenev 1]

Еще вопрос небольшой (я надеюсь) возник, напишу сюда же.

Документирую сами файлы вот таким образом:

Спойлер

/**
\file adc_module.h
\brief Хидер файл для adc_module.c. Содержит общие определения приложения.
*/

 \details - подробное описание, почти не использую.

Проблема в том, что в выходной документации дублируется то, что было указано в \brief. Сначала сразу под названием файла (скрин), а потом в графе "Подробное описание" (скрин):

Спойлер

Как бы удалить содержимое brief из подробного описания, оставив только в самом начале? На крайний случай удалить содержимое brief из начала, оставив только подробном описании.

[EdgeAligned 53]

Во вкладке Project убрать галочку в Repeat Brief

[EdgeAligned 53]

По поводу дублирования документации в .h-файлах. В принципе, эти файлы в языке Си представляют интерфецсы модулей и вполне даже логично, что инфа по всем публичным (глобальным) функциям показывается в описании этого файла. Исходные файлы могут быть скомпилированы в закрытые библиотеки, а .h в таком случае остаётся единственным открытым файлом.

[Turgenev 1]

44 минуты назад, EdgeAligned сказал:

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

Могут быть скомпилированы в закрытые, а могут и нет)) я так понимаю, это все же не стандарт.

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

[GeorgK 1]

По поводу дублирования с сишном и заголовочном файле - делал так: в описании сишного файла ссылаюсь на описание из заголовка:

  /**
   * \file
   * * \copybrief express::AGGREGATE_GENERIC::is_set_and_bag_instance_equal(const express::AGGREGATE_GENERIC&) const
   */
  LOGICAL AGGREGATE_GENERIC::is_set_and_bag_instance_equal(const AGGREGATE_GENERIC& rhs) const {

    /**
     * Алгоритм:
     *
     * 1) Если какой-либо из операндов имеет неопределённое (\ref p11_s14_2 "?") значение, то результатом
     * сравнения является \ref p11_s14_7 "UNKNOWN" (см. \ref p11_s12_2 "п.12.2").
     */
    if (is_nil() || rhs.is_nil()) {
      return UNKNOWN;
    }

А в заголовочном файле даю полное описание:

    /**
     * \brief Проверка равенства экземпляров (ГОСТ Р ИСО 10303-11-2009, \ref p11_s12_2_2_1 "п.12.2.2.1")
     * текущего \ref express::SET_GENERIC "набора" и указанного \ref express::BAG_GENERIC "пакета"
     *
     * \param [in] rhs \ref express::BAG_GENERIC "Пакет", с которым выполняется сравнение,
     * в виде константной ссылки на тип \ref express::AGGREGATE_GENERIC "AGGREGATE_GENERIC".
     * \retval TRUE если \ref express::SET_GENERIC "набор" и \ref express::BAG_GENERIC "пакет" равны;
     * \retval FALSE если \ref express::SET_GENERIC "набор" и \ref express::BAG_GENERIC "пакет" не равны;
     * \retval UNKNOWN если результат сравнения \ref express::SET_GENERIC "набора" и
     * \ref express::BAG_GENERIC "пакета" не определён.
     */
    LOGICAL is_set_and_bag_instance_equal(const AGGREGATE_GENERIC& rhs) const;

Тогда физически описание только в заголовочном файле, а в документации - и там, и там (в разных разделах про разные файлы).

[EdgeAligned 53]

Так описание и пишется физически только в одном файле. Но в документацию вносится в оба. Об этом и был вопрос.

[Turgenev 1]

14 часов назад, GeorgK сказал:

Тогда физически описание только в заголовочном файле, а в документации - и там, и там (в разных разделах про разные файлы).

А как же комментарии, которые внутри функции (комментарии к операциям из которых состоит функция)?

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

Для меня логично размещение описания и комментариев к функции в одном файле: разбираешься с функцией, значит читаешь к ней краткое описание, если этого не достаточно, тут тебе сразу под описанием ее реализация с комментариями. А разносить описание функции и комментарии к ней по разным файлам ну не удобно. Если делать это только ради Doxygen'а, странновато для меня. Сугубо мой взгляд на ситуацию.

 

Изменено 5 октября, 2023 пользователем Turgenev

[Turgenev 1]

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

[EdgeAligned 53]

Да, конечно. Вы можете создать свой шаблон стилей и указать в настройках на вкладке HTML пути к ним. Подробности на сайтe doxygen.nl