Doxygen (или другой инструмент) документируют классы и пространства имен аналогично, если находятся на одном уровне - PullRequest
Новая
       20

Doxygen (или другой инструмент) документируют классы и пространства имен аналогично, если находятся на одном уровне

0 голосов
/ 28 февраля 2019

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

  • proj/pkg1/foo.hpp: class proj::pkg1::Foo
  • proj/pkg1/bar.hpp: class proj::pkg1::Bar
  • proj/pkg1/baz.hpp: namespace proj::pkg1::Baz
  • proj/pkg2/one.hpp: class proj::pkg2::One
  • proj/pkg2/two.hpp: namespace proj::pkg2::Two

У меня нет комментариев @file.Они были бы полностью избыточными, потому что уже есть один главный комментарий для каждого компонента, который присоединен к основному классу или пространству имен.

Я попытался запустить это через Doxygen, и в результате получился беспорядок:

  • Пространства имен и классы разделены на две разные иерархии, как в строке заголовка, так и на панели навигации.Но я хочу, чтобы они все были в одном дереве, потому что, например, pkg2::One принадлежит вместе с pkg2::Two.
  • Основная иерархия пространств имен скрыта на трех уровнях вниз по панели навигации (Имя проекта -> пространства имен -> список пространств имен).Это рядом с «Членами пространства имен» - кто это использует??
  • Существует другая иерархия для файлов (и каталогов).Это избыточно, потому что они точно соответствуют иерархии пространств имен (и классов).
  • Сейчас это немного отвлекает, но я также хотел бы добавить комментарии к пространствам имен пакета.У них та же проблема разделения классов и пространств имен (не такая уж большая проблема), но также отображаются различные свободные функции, например, operator<<(proj::pkg2::One.

Есть ли способ немного почистить вещи?Может быть, со Sphinx и Breathe?

Пример снимка экрана

Вот что Doxygen производит по умолчанию в приведенном выше коде (в нем даже не упоминаются Baz и Two!), Икак я предпочитаю, чтобы это выглядело:

Example mock screen shot

Ответы [ 2 ]

0 голосов
/ 28 февраля 2019

Это особенно ужасный взлом, но я упомянул его для записи.Вы можете решить, что с классами лучше всего справляется Doxygen, и переназначить все пространства имен компонентов (третьего уровня) на классы.Вот так: 

namespace proj {
namespace pkg1 {

/// @brief The Doxygen comment goes here.
#ifdef DOXYGEN
class
#else
namespace
#endif
Baz {

Затем установите PREDEFINED = DOXYGEN в Doxyfile.

Очевидно, что недостатками этого являются то, что в исходном коде это выглядит уродливо как грех, и этозаблуждение, что в документации это проявляется как «класс».

0 голосов
/ 28 февраля 2019

Чтобы сдвинуться с мертвой точки, вот возможное решение:

Измените ожидания немного: вместо того, чтобы надеяться, что двухуровневая структура будет представлена ​​читателям за один раз, смиритесь с представленной частью.вовремя.Заставьте пользователя щелкнуть по отдельной странице для каждого пространства имен в дереве:

  • На странице документации для пространства имен proj показаны все содержащиеся в ней пакеты (т. Е. В примере показаны пространства именpkg1 и pkg2).

  • На каждой странице пространства имен пакетов показаны все классы и пространства имен компонентов в ней (в отдельных списках, что немного раздражает, но по крайней мере все содержимое для каждого пакета объединено).

Вы можете скрыть древовидное представление с помощью GENERATE_TREEVIEW=NO и скрыть строку заголовка DISABLE_INDEX=YES.

Главная страница может быть просто ссылкой на верхний уровень proj страница пространства имен (с обычным содержимым главной страницы, перемещенным в подробное описание proj) с кодом, подобным следующему: 

/**
@mainpage
@ref proj "Click here for the proj documentation"
*/

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

/**
@mainpage

Packages:
- @ref proj::pkg1 @n @copybrief proj::pkg1
- @ref proj::pkg2 @n @copybrief proj::pkg2
*/
...