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

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

Так вот и получается непонятно зачем до сих пор используют доксиген.

Кому-нибудь реально помогала документация, сгенерированная доксигеном?

Здравствуйте, koenjihyakkei, Вы писали:

K>Тут изучая очередной проект, поймал себя на мысли, что никогда не читаю документацию, сгенерированную доксигеном.
А её невозможно читать, уж лучше сразу в сурсы посмотреть.

K>Если хочется почитать комментарии к функциям, классам и т.д., то проще открыть исходники, там и по коду сразу погулять можно.
K>Если хочется почитать общую документацию, то она обычно пишется отдельно, в каком-нибудь маркдауне.
+1

Более того эти докси-каменты порой не соответствуют действительности: код поменялся а каментами лень заниматься или отложили на потом и забыли. Да и вообще вроде бы в этих ваших доксигенах информации много, но с другой стороны посмотришь а зачем так много, какая-то хрень малозначительная, полстаницы параметры функций, зачем они мне сейчас? Как это зафильтровать? И там еще непонятно где начало где конец, просто по алфавиту список классов или функций или еще чего, диграммы классов сгенеририованы примитивные. Причем это вовсе не бесплатно дается как они типа говорят, надо внимательно следить за изменениями в коде, каменты править, там какие то неведомые ключевые слова , надо не ошибиться и т.д. Норм доки пишут не компиляторы а люди для людей: последовательно, логично, с теми же диаграммами классов на них не все подряд что попало, а те что нужны были этого текста.

Здравствуйте, koenjihyakkei, Вы писали:

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

K>Так вот и получается непонятно зачем до сих пор используют доксиген.

K>Кому-нибудь реально помогала документация, сгенерированная доксигеном?


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

Здравствуйте, koenjihyakkei, Вы писали:

K>Так вот и получается непонятно зачем до сих пор используют доксиген.
K>Кому-нибудь реально помогала документация, сгенерированная доксигеном?

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

Здравствуйте, koenjihyakkei, Вы писали:

K>Кому-нибудь реально помогала документация, сгенерированная доксигеном?

Да.

Здравствуйте, koenjihyakkei, Вы писали:

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

Плохо написана?

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

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

K>Кому-нибудь реально помогала документация, сгенерированная доксигеном?

Да, постоянно.
Начиная с того, что один класс может быть распределён между 100500 файлами, а тут она компактно собрана

Здравствуйте, koenjihyakkei, Вы писали:

K>Так вот и получается непонятно зачем до сих пор используют доксиген.

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

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

И третье, потенциально IDE может при наведении курсора мыши (или по shortcut)
показать уже "отрендеренные" комментарии для данной функции. В IDE для C++ такого
не встречал, но в IDE для других языков видел. Довольно удобно, к реализации/объявлению
самой функции/типа переходить не надо, можно прочитать комментарии к ней прямо в месте
использования функции/типа,
и за счет того, что комментарий, показываемый в сплывающем окне,
это отрендеренный текст, с шрифтами разной толщины и цвета, легче найти нужную информацию.

Здравствуйте, koenjihyakkei, Вы писали:

K>Тут изучая очередной проект, поймал себя на мысли, что никогда не читаю документацию, сгенерированную доксигеном.
K>То есть буквально только что, открыл доку проекта, увидел, что это доксиген, и сразу закрыл.
Это значит, что доку писали "на отвали", доксиген тут непричём.

K>Кому-нибудь реально помогала документация, сгенерированная доксигеном?
Доксиген это тулза. Она волшебство не делает. Как я понимаю, его изобрели по образу и подобию javadoc. Вот возьмём примерчик. Зачем тебе может понадобится лезть в исходники после такой доки?

Здравствуйте, koenjihyakkei, Вы писали:

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

Это твой психологический комплекс. Комплексы лечить надо.

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

K>Так вот и получается непонятно зачем до сих пор используют доксиген.

K>Кому-нибудь реально помогала документация, сгенерированная доксигеном?

Доксиген — гениальное изобретение, которое:
1) Заставляет программистов писать документацию.
2) Позволяет писать документацию одновременно с кодом
3) Следит за тем, чтобы исходники и дока сильно не разбегались.
4) Позволяет делать это всё практически не напрягаясь.

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

Кто-то с помощью доксигена делает плохую документацию?
Ну, сдуру можно и хрен сломать. Инструмент в этом не виноват.

Здравствуйте, netch80, Вы писали:

N>Плохо написана?

Можно примеры где хорошо написана?

Например, в таком популярном проекте как LLVM, я доксиген никогда не читал, потому что есть отдельные хорошие доки.

N>И достаточно часто без комментариев фиг поймёшь, _почему_ так делается

Я же не говорю, что комментарии не нужны, просто я думаю, что мало кто читает их в сгенерированном html, большинство в сорцах. Может ошибаюсь, поэтому и спрашиваю — может кто-то привести примеры, где реально доксигеновская дока помогла.

N>Да, постоянно.
N>Начиная с того, что один класс может быть распределён между 100500 файлами, а тут она компактно собрана

И еще раз, можно примеры?

Здравствуйте, Zhendos, Вы писали:

Z>Ну первый очевидный вариант использования, это предварительный выбор библиотеки,
Z>прежде чем качать ее исходный код, собирать и так далее проще сначала
Z>html на сайте библиотеки посмотреть есть ли то что нужно и насколько это удобно.

Возможно у меня претензия к внешнему виду сгенерированного html.

Z>И третье, потенциально IDE может при наведении курсора мыши (или по shortcut)
Z>показать уже "отрендеренные" комментарии для данной функции. В IDE для C++ такого
Z>не встречал, но в IDE для других языков видел. Довольно удобно, к реализации/объявлению
Z>самой функции/типа переходить не надо, можно прочитать комментарии к ней прямо в месте
Z>использования функции/типа,
Z>и за счет того, что комментарий, показываемый в сплывающем окне,
Z>это отрендеренный текст, с шрифтами разной толщины и цвета, легче найти нужную информацию.

С этим не спорю, я спрашиваю только про сгенерированную документацию, ее читабельность и нужность.

Здравствуйте, alpha21264, Вы писали:

A>Например, доксигеном сделана докуменация для Qt.
A>Это вообще самая лучшая документация, которую я видел за всю свою жизнь.

Ну принцип похож, но doxygen в Qt не используется.
У них собственная утилита qdoc на основе clang генерирует документацию из комментариев.

Здравствуйте, ·, Вы писали:

·>Это значит, что доку писали "на отвали", доксиген тут непричём.

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

·>Доксиген это тулза. Она волшебство не делает. Как я понимаю, его изобрели по образу и подобию javadoc. Вот возьмём примерчик. Зачем тебе может понадобится лезть в исходники после такой доки?

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

Здравствуйте, alpha21264, Вы писали:

A>Это твой психологический комплекс. Комплексы лечить надо.

От людей с совковым флагом в подписи другого комментария и не ожидаешь

A>Доксиген — гениальное изобретение, которое:
A>1) Заставляет программистов писать документацию.
A>2) Позволяет писать документацию одновременно с кодом
A>3) Следит за тем, чтобы исходники и дока сильно не разбегались.
A>4) Позволяет делать это всё практически не напрягаясь.

Сдается мне, что это все не заслуга доксигена, а Coding Standards проекта.

A>Например, доксигеном сделана докуменация для Qt.
A>Это вообще самая лучшая документация, которую я видел за всю свою жизнь.

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

Здравствуйте, koenjihyakkei, Вы писали:

K>·>Это значит, что доку писали "на отвали", доксиген тут непричём.
K>Ну так 99% именно таких, но они упорно продолжают тянуть доксиген в свои проекты. Некоторые даже тянут ее (сгенерированную документацию) в репозиторий, хотя она почти полностью пуста, вот пример.
Культ Карго, похоже. Всё равно не объясняет причём тут доксиген. Можно найти примеры и бессмысленного отвратительного javadoc.

K>·>Доксиген это тулза. Она волшебство не делает. Как я понимаю, его изобрели по образу и подобию javadoc. Вот возьмём примерчик. Зачем тебе может понадобится лезть в исходники после такой доки?
K>Согласен, во многих других языках сгенерированная документация весьма полезна и читабельна, в том же питоне, руби и т.д. Там и верстка симатичнее.
Впрочем, я может не знаю что-то о доксигене. Может в нём сложно писать нормальную документацию или настраивать вёрстку.

Здравствуйте, koenjihyakkei, Вы писали:

K>Кому-нибудь реально помогала документация, сгенерированная доксигеном?

Да, конечно. Сравни: код и https://docs.opencv.org/4.7.0/d6/dc7/group__imgproc__hist.html#ga994f53817d621e2e4228fc646342d386.

Для наглядности.
Код:

/** Histogram comparison methods
  @ingroup imgproc_hist
*/
enum HistCompMethods {
    /** Correlation
    \f[d(H_1,H_2) =  \frac{\sum_I (H_1(I) - \bar{H_1}) (H_2(I) - \bar{H_2})}{\sqrt{\sum_I(H_1(I) - \bar{H_1})^2 \sum_I(H_2(I) - \bar{H_2})^2}}\f]
    where
    \f[\bar{H_k} =  \frac{1}{N} \sum _J H_k(J)\f]
    and \f$N\f$ is a total number of histogram bins. */
    HISTCMP_CORREL        = 0,
    /** Chi-Square
    \f[d(H_1,H_2) =  \sum _I  \frac{\left(H_1(I)-H_2(I)\right)^2}{H_1(I)}\f] */
    HISTCMP_CHISQR        = 1,
    /** Intersection
    \f[d(H_1,H_2) =  \sum _I  \min (H_1(I), H_2(I))\f] */
    HISTCMP_INTERSECT     = 2,
    /** Bhattacharyya distance
    (In fact, OpenCV computes Hellinger distance, which is related to Bhattacharyya coefficient.)
    \f[d(H_1,H_2) =  \sqrt{1 - \frac{1}{\sqrt{\bar{H_1} \bar{H_2} N^2}} \sum_I \sqrt{H_1(I) \cdot H_2(I)}}\f] */
    HISTCMP_BHATTACHARYYA = 3,
    HISTCMP_HELLINGER     = HISTCMP_BHATTACHARYYA, //!< Synonym for HISTCMP_BHATTACHARYYA
    /** Alternative Chi-Square
    \f[d(H_1,H_2) =  2 * \sum _I  \frac{\left(H_1(I)-H_2(I)\right)^2}{H_1(I)+H_2(I)}\f]
    This alternative formula is regularly used for texture comparison. See e.g. @cite Puzicha1997 */
    HISTCMP_CHISQR_ALT    = 4,
    /** Kullback-Leibler divergence
    \f[d(H_1,H_2) = \sum _I H_1(I) \log \left(\frac{H_1(I)}{H_2(I)}\right)\f] */
    HISTCMP_KL_DIV        = 5
};

Документация:

Здравствуйте, koenjihyakkei, Вы писали:

K>Может ошибаюсь, поэтому и спрашиваю — может кто-то привести примеры, где реально доксигеновская дока помогла.

Из недавнего. Номер раз: https://www.angelcode.com/angelscript/sdk/docs/manual/index.html Документация по встраиваемому языку AngelScript. Прямо в doxygen-е и вменяемое описание самого языка, и API Reference. И хотя API Reference, как часто бывает, весьма скудны, в качестве справочника вполне себе OK.

Пример номер два: FFMPEG. Там документация вообще не ахти (сильно не ахти, как по мне). И Doxygen-овская не исключение. Но, зато в Doxygen-е генерируется все, включая даже исходники. И глядя на какую-нибудь avcodec_find_encoder можно по ссылкам провалиться в ее реализацию, а оттуда и по реализациям потрохов этой функции.

Ну и из нескромного: мы своими библиотеками так давно занимаемся, что зачастую многого уже не вспомнить. Так что сгенерированная по исходникам Doxygen документация мной лично используется чуть ли не повседневно (найти точное название метода/функции, вспомнить набор параметров, подсмотреть пример вызова и т.д., и т.п.).

доксиген — генератор избыточного мусора
нет, ненужен

даже те кто ссылаются мол навигацию хождениям по ссылкам
видимо только виртуально по тем ссылкам ходят

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

Здравствуйте, reversecode, Вы писали:

R>навигацию без файлового менеджера вообще сложно делать
R>когда нужно сразу штук 20-30 открытых файлов держать что бы все понять

в браузерах-то вкладки давно появились