отличный пример кода который пишут математики

давайте я упрощу

enum 
{
  /** почему здесь начинается не с нуля смотрите в доксиген
    \g[f]e+443+ f\ffff\start\end\nafig [formula]abs noobs da_iditi
   **/
  /** это очень сложно объяснить что это за переменная читайте доксиген
   \foo\babah fmin[dot] max nah mjau \sin alpha
   **/
  HREN_ZNAET_4TO_0 = 1,
  /** это очень сложно объяснить что это за переменная читайте доксиген
   \nipel\shangen_cirkul \blah\blah
   **/
  HREN_ZNAET_4TO_1 = 2,
  /** это очень сложно объяснить что это за переменная читайте доксиген
   \start_supper{lenivo}
   **/
  HREN_ZNAET_4TO_2 = 3,
  /** это очень сложно объяснить что это за переменная читайте доксиген
   \fac[fac[fac[fac[none]]]] mul [zero] exp [zero]
   **/
  HREN_ZNAET_4TO_3 = 4,
  /** это очень сложно объяснить что это за переменная читайте доксиген
   EMPTY //TODO
   **/
  HREN_ZNAET_4TO_4 = 5,
};

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Да.

Здравствуйте, 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 открытых файлов держать что бы все понять

умеет умеет
но видимо это нужно тем программистам которые в IDE сидят
и без визуал ассиста кодить не умеют
а без lsp к IDE или к VIM сразу сливаются на собеседованиях

я уж так привык что все стараюсь помнить особенно если он хот с этим работаю
и для памяти полезно

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

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

Например, в библиотечном коде я не вижу ничего плохого в высокой связности. Это говорит о том, что библиотека хорошо спроектирована, а её сущности — объективно взаимозависимы, а не просто всякий случайный хлам, собранный в кучу. В не-библиотечном коде это может сигналить о нарушении разделения ответственности.

Так вот, для библиотек Доксиджен (или любая другая самосборная документация) это must have. А для не-библиотечного кода я большого прока в ней не вижу. Разница в том, что с библиотекой я принципиально хочу работать как с чёрным ящиком, не забивая себе голову деталями реализации. Править популярные библиотеки, опять же, никто не правит — пишут тикет автору, ждут обновления. А не-библиотечный код ты и читаешь, и сам дописываешь.

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

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

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

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

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

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

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

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

Вот и получается, что doxygen-комментарии как общий принцип в среднем более чем удобны.

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

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

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

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

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

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

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


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

Здравствуйте, 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>это отрендеренный текст, с шрифтами разной толщины и цвета, легче найти нужную информацию.

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

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

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

Ну так 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>Согласен, во многих других языках сгенерированная документация весьма полезна и читабельна, в том же питоне, руби и т.д. Там и верстка симатичнее.
Впрочем, я может не знаю что-то о доксигене. Может в нём сложно писать нормальную документацию или настраивать вёрстку.

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

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

Или не все его возможности знаешь. Ещё он умеет, например, формулы и графы, которые в текстовом виде не наглядны или не читабельны, а в графическом очень даже естественно выглядят.

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

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

Вообще, вот интересно. Я тоже всегда так относился к автосгенеренной документации, как ты. Но вся документация по Go, вообще вся — автосгерененная. Однако же в среднем очень толковая. Иногда даже какую-нибудь сишную библиотеку проще понять не из ее собственной документации, а из гошной обертки.

Почему так, не знаю. Загадка природы. То ли гошные инструменты, в т.ч. для документирования кода, в разы лучше, чем сишные. То ли культура производства у гошников другая.

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

K>Вопрос про обычные проекты.

Почему в обычных проектах херовая документация, c doxygen ли, без него ли?

Потому что индустрия хреновая.

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

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

Использую в виде, когда при наведении мышкой на метод/класс в IDE всплывает отформатированная подсказка, что делает метод, какие параметры, и т.д.