Doxygen: документирование
Модератор: Olej
- Olej
- Писатель
- Сообщения: 21338
- Зарегистрирован: 24 сен 2011, 14:22
- Откуда: Харьков
- Контактная информация:
Doxygen: документирование
Документирование создаваемого программного кода - это составная часть технологии, не менее важная, чем само создание кода и его тестирование и отладка.
Беда в том, что разработчики об этом особенно не хотят знать
И это особенно актуально при переходе к опенсорсной модели ...
Потому что некоторые проприетарные продукты имели шикарную документацию (к Microsoft и Windows это лирическое отступление не имеет отношения ).
Примеры такой шикарной документации ... былых времён:
1. Система документирования IBM 360 ... позже переведенная и адаптированная к сеейству ЕС ЭВМ - документация по ОС/ЕС составляла ... "2 метра на книжной полке", это не менее 50 или 70 книг, некоторые из которых по 10-15 страниц, но основополагающие: FORTRAN, PL/1 ... имели по 300-400-500 страниц.
2. Документация операционной системы реального времени QNX 6 Neutrino - это онлайн иерархическая документация ... но образца такой детализации описаний по POSIX (UNIX) стандартам я вообще не видел ... особенно по расширениям POSIX реального времени: 1003b, 1003g и др.
Для проприетарного ПО полнота и прозрачность документации - это был важный фактор её продаваемости
Для опенсорс как раз отсутствие документации становится заметным фактором финансового благополучия производителя: зараьоток теперь происходит не с продаж ПО или лицензий, а с последующих консультаций по использованию, внедрению и техподдержке.
Блестяший пример тут RedHat - ставший крупнейшей финансовой империей на Linux ... и упадок и нищета IBM из мира проприетарного (а когда-то в IT было 2 актора, участника: IBM + все остальные ).
Про это всё эсть у нас уже тема здесь обсуждения Бизнес-модели в IT производстве - там много деталей...
А сейчас, эта тема, она интересует меня относительно средства автодокументирования Doxygen.
Беда в том, что разработчики об этом особенно не хотят знать
И это особенно актуально при переходе к опенсорсной модели ...
Потому что некоторые проприетарные продукты имели шикарную документацию (к Microsoft и Windows это лирическое отступление не имеет отношения ).
Примеры такой шикарной документации ... былых времён:
1. Система документирования IBM 360 ... позже переведенная и адаптированная к сеейству ЕС ЭВМ - документация по ОС/ЕС составляла ... "2 метра на книжной полке", это не менее 50 или 70 книг, некоторые из которых по 10-15 страниц, но основополагающие: FORTRAN, PL/1 ... имели по 300-400-500 страниц.
2. Документация операционной системы реального времени QNX 6 Neutrino - это онлайн иерархическая документация ... но образца такой детализации описаний по POSIX (UNIX) стандартам я вообще не видел ... особенно по расширениям POSIX реального времени: 1003b, 1003g и др.
Для проприетарного ПО полнота и прозрачность документации - это был важный фактор её продаваемости
Для опенсорс как раз отсутствие документации становится заметным фактором финансового благополучия производителя: зараьоток теперь происходит не с продаж ПО или лицензий, а с последующих консультаций по использованию, внедрению и техподдержке.
Блестяший пример тут RedHat - ставший крупнейшей финансовой империей на Linux ... и упадок и нищета IBM из мира проприетарного (а когда-то в IT было 2 актора, участника: IBM + все остальные ).
Про это всё эсть у нас уже тема здесь обсуждения Бизнес-модели в IT производстве - там много деталей...
А сейчас, эта тема, она интересует меня относительно средства автодокументирования Doxygen.
- Olej
- Писатель
- Сообщения: 21338
- Зарегистрирован: 24 сен 2011, 14:22
- Откуда: Харьков
- Контактная информация:
Doxygen: документирование
Doxygen
Doxygen — кроссплатформенная система документирования исходных текстов, которая поддерживает C++, Си, Objective-C, Python, Java, IDL, PHP, C#, Фортран, VHDL и, частично, D.
Doxygen генерирует документацию на основе набора исходных текстов и также может быть настроен для извлечения структуры программы из недокументированных исходных кодов. Возможно составление графов зависимостей программных объектов, диаграмм классов и исходных кодов с гиперссылками.
Doxygen имеет встроенную поддержку генерации документации в формате HTML, LAΤΕΧ, man, RTF и XML. Также вывод может быть легко сконвертирован в CHM, PostScript, PDF.
Doxygen используется многими проектами, в том числе KDE, Pidgin, Torque Game Engine, AbiWord, Mozilla, FOX toolkit, Crystal Space, Drupal. Есть встроенная поддержка в KDevelop.
Doxygen — консольная программа в духе классической Unix. Она работает подобно компилятору, анализируя исходные тексты и создавая документацию. Параметры создания документации читаются из конфигурационного файла, имеющего простой текстовый формат.
Для упрощения манипуляций с конфигурационным файлом (а он содержит довольно много настроек), существует несколько утилит с графическим интерфейсом. Одна из них, doxywizard, поставляется вместе с Doxygen.
- Olej
- Писатель
- Сообщения: 21338
- Зарегистрирован: 24 сен 2011, 14:22
- Откуда: Харьков
- Контактная информация:
Doxygen: документирование
... но подвигла меня на эту отдельную тему свежая хорошая статья на Хабре - Автодокументация Doxygen и её развертывание на GitHub Pages
9 мар в 17:00
Я очень люблю писать код. И вот насколько я люблю писать его, настолько же я не люблю писать документацию, но при этом осознаю всю её важность. Можно писать всю сопроводительную информацию прямо в коде, и написание комментариев является хорошим тоном, так как позволяет проще разобраться в структуре программы или библиотеки. Описание функций или классов прямо в файлах проекта удобно, когда программист видит исходники перед собой и работает непосредственно с ним, но если кто‑то хочет использовать код как черный ящик, и ему мало важны исходники, так как он пользуется, например, готовыми бинарными файлами. В такой ситуации искать необходимые файлы, например, заголовочные для C++, по разным папкам компьютера не очень удобно, и хотелось бы иметь полноценную документацию в одном месте.
Пожалуй, самым популярным типом документации являются сайты на HTML. Однако процесс ручного ведения документации не очень прост, так как необходимо постоянно следить за соответствием между сайтом и проектом, и поэтому были созданы программные методы для извлечения всех данных о классах, функциях и их параметрах, перегрузках и шаблонах. Поскольку информация о всех сущностях проекта извлекается из кода, то в нем же можно и размещать все или почти все описание.
И более старый подробный цикл:Doxygen — это система автоматического документирования. Он поддерживает множество разных типов выходной документации, например HTML и man-файлы, но в статье будет информация только об HTML. Doxygen обрабатывает код, достает из него всё, что указано в настройках, например классы и их методы, добавляет информацию об этих методах в документацию, а затем вставляет описание из комментариев из исходников в доки.
Но каким образом он понимает, какой текст нужно извлекать? Для этого все комментарии должны быть написаны в определенном формате. Я не буду углубляться в этот формат, так как на «Хабре» есть отличный цикл статей, посвященный всей системе. Важно сказать, что Doxygen поддерживает markdown внутри комментариев, что очень удобно.
Документируем код эффективно при помощи Doxygen
6 мар 2015 в 07:37
Данная статья входит в получившийся цикл статей о системе документирования Doxygen:
1. Документируем код эффективно при помощи Doxygen
2. Оформление документации в Doxygen
3. Построение диаграмм и графов в Doxygen
- Olej
- Писатель
- Сообщения: 21338
- Зарегистрирован: 24 сен 2011, 14:22
- Откуда: Харьков
- Контактная информация:
Doxygen: документирование
Код: Выделить всё
olej@R420:~$ aptitude search doxy
p doxygen - Documentation system for C, C++, Java, Python and other languages
p doxygen:i386 - Documentation system for C, C++, Java, Python and other languages
p doxygen-doc - документация по doxygen
v doxygen-doc:i386 -
v doxygen-docs -
p doxygen-doxyparse - multi-language source code parser based on Doxygen
p doxygen-doxyparse:i386 - multi-language source code parser based on Doxygen
p doxygen-gui - Инструмент настройки doxygen с графическим интерфейсом
p doxygen-gui:i386 - Инструмент настройки doxygen с графическим интерфейсом
p doxygen-latex - Documentation system for C, C++, Java, Python and other languages
v doxygen-latex:i386 -
p doxygen2man - generate man pages from Doxygen XML files
p doxygen2man:i386 - generate man pages from Doxygen XML files
v doxypypy -
p doxyqml - QML-фильтр для Doxygen
p libdoxygen-filter-perl - Methods for pre-filtering Perl code for Doxygen
p python3-doxypypy - More Pythonic version of doxypy, a Doxygen filter for Python
Код: Выделить всё
olej@R420:~/2024/own.BOOKs/BHV.Go.3/examples.work/git/github$ sudo apt install doxygen doxygen-gui
[sudo] пароль для olej:
Чтение списков пакетов… Готово
Построение дерева зависимостей… Готово
Чтение информации о состоянии… Готово
Предлагаемые пакеты:
doxygen-latex doxygen-doc
Следующие НОВЫЕ пакеты будут установлены:
doxygen doxygen-gui
Обновлено 0 пакетов, установлено 2 новых пакетов, для удаления отмечено 0 пакетов, и 0 пакетов не обновлено.
Необходимо скачать 4.900 kB архивов.
После данной операции объём занятого дискового пространства возрастёт на 18,9 MB.
Пол:1 http://ubuntu.colocall.net/ubuntu jammy/universe amd64 doxygen amd64 1.9.1-2ubuntu2 [4.620 kB]
Пол:2 http://ubuntu.colocall.net/ubuntu jammy/universe amd64 doxygen-gui amd64 1.9.1-2ubuntu2 [280 kB]
Получено 4.900 kB за 3с (1.921 kB/s)
Выбор ранее не выбранного пакета doxygen.
(Чтение базы данных … на данный момент установлено 595598 файлов и каталогов.)
Подготовка к распаковке …/doxygen_1.9.1-2ubuntu2_amd64.deb …
Распаковывается doxygen (1.9.1-2ubuntu2) …
Выбор ранее не выбранного пакета doxygen-gui.
Подготовка к распаковке …/doxygen-gui_1.9.1-2ubuntu2_amd64.deb …
Распаковывается doxygen-gui (1.9.1-2ubuntu2) …
Настраивается пакет doxygen (1.9.1-2ubuntu2) …
Настраивается пакет doxygen-gui (1.9.1-2ubuntu2) …
Обрабатываются триггеры для man-db (2.10.2-1) …
Обрабатываются триггеры для menu (2.1.47ubuntu4) …
Код: Выделить всё
olej@R420:~/2024/own.BOOKs/BHV.Go.3/examples.work/git/github$ apt content doxygen
/.
/usr
/usr/bin
/usr/bin/dh_doxygen
/usr/bin/doxygen
/usr/bin/doxyindexer
/usr/bin/doxysearch.cgi
/usr/share
/usr/share/doc
/usr/share/doc/doxygen
/usr/share/doc/doxygen/changelog.Debian.gz
/usr/share/doc/doxygen/copyright
/usr/share/doc/doxygen/LANGUAGE.HOWTO
/usr/share/doc/doxygen/NEWS.Debian.gz
/usr/share/doc/doxygen/README.jquery
/usr/share/doc/doxygen/README.md
/usr/share/doc/doxygen/TODO.Debian
/usr/share/doc/doxygen/VERSION
/usr/share/man
/usr/share/man/man1
/usr/share/man/man1/dh_doxygen.1.gz
/usr/share/man/man1/doxygen.1.gz
/usr/share/man/man1/doxyindexer.1.gz
/usr/share/man/man1/doxysearch.1.gz
/usr/share/man/man1/doxysearch.cgi.1.gz
Код: Выделить всё
olej@R420:~/2024/own.BOOKs/BHV.Go.3/examples.work/git/github$ which doxygen
/usr/bin/doxygen
Код: Выделить всё
olej@R420:~/2024/own.BOOKs/BHV.Go.3/examples.work/git/github$ apt content doxygen-gui
/.
/usr
/usr/bin
/usr/bin/doxywizard
/usr/share
/usr/share/doc
/usr/share/doc/doxygen-gui
/usr/share/doc/doxygen-gui/changelog.Debian.gz
/usr/share/doc/doxygen-gui/copyright
/usr/share/man
/usr/share/man/man1
/usr/share/man/man1/doxywizard.1.gz
/usr/share/menu
/usr/share/menu/doxygen-gui
Код: Выделить всё
olej@R420:~/2024/own.BOOKs/BHV.Go.3/examples.work/git/github$ which doxywizard
/usr/bin/doxywizard
Код: Выделить всё
olej@R420:~/2024/own.BOOKs/BHV.Go.3/examples.work/git/github$ doxywizard
...
- Olej
- Писатель
- Сообщения: 21338
- Зарегистрирован: 24 сен 2011, 14:22
- Откуда: Харьков
- Контактная информация:
Doxygen: документирование
Но меня то интересует ... не "частично, D", а - GoLang.
И если посмотреть поиском - Go: пакеты для импорта (библиотеки) поиск:
Код: Выделить всё
olej@R420:~/2024/own.BOOKs/BHV.Go.3/examples.work/looking.for/find.pkg$ ./find.curl.sh Doxygen
9
"/github.com/openllb/doxygen-parser/doxygen"
"/github.com/dennwc/go-doxy"
"/github.com/shanduur/go-doxygen-generator/command"
"/github.com/alexaandru/go-sitter-forest/doxygen"
"/github.com/qiniu/doxygen.io"
"/github.com/rcurtin/mlpackgo"
"/github.com/rcurtin/mlpack-go"
"/mlpack.org/v1/mlpack"
"/github.com/nuald/adx"
И все они, если посмотреть Web поиском, то все они 2022, 2023 и 2024 годов.
Кто сейчас на конференции
Сейчас этот форум просматривают: нет зарегистрированных пользователей и 4 гостя