Comments 39
Достойная шпаргалка. Спасибо!
А есть какая-нибудь функция или программа, которая сможет заставить комментировать код?
Есть, называется «метод административного произвола» :)
Atomineer Pro Documentation для VS умеет автоматически проставлять комментарии на основе какого-то шаблона, но стоит денег.
QtCreator умеет рисовать сами блоки с тегами описания и параметров при вводе "/*!" и нажатии на Enter.
Совсем отдельных софтин я не встречал, что странно, на самом деле.
QtCreator умеет рисовать сами блоки с тегами описания и параметров при вводе "/*!" и нажатии на Enter.
Совсем отдельных софтин я не встречал, что странно, на самом деле.
Мы делаем следующим образом: в настройках нужных сборок ставится галочка «XML documentation file». Далее первращаем warnings в errors. Profit: если кто-то не прописал xml-документацию для публичной сущности, то код просто не будет компилироваться.
Программы нет. Но есть одно заклинание, которое применяют маги 2 уровня(насяльника). Магу 2 уровня достаточно произнести «Вы действительно хотите зарплату?». После произнесения этого заклинания успешно материализуются из кнопок, пальцев, остатков мозга в комментарии в коде ;)
Эх, а если сам себе насяльник?
У любого насяльника есть другой насяльника, к примеру дядя дающий денег за написанный продукт. И тогда заклинание «Вы действительно хотите зарплату?» неявным образом вызывает заклинание «Что Вы можете мне предложить чтобы у меня появилось желание дать Вам денег?». Рынок это тоже насяльника и как правило более суровый ;)
Меня в работе с doxygen'ом отталкивает в первую очередь структура порождаемого документа — вылезает много лишнего, что-то хочется поправить/перенести и т.д. А любое редактирование конечного получаемого документа убивает сразу всю идею… Возможно просто недостаточно курил документацию на него.
А статья полезная, заизбранил ;)
А статья полезная, заизбранил ;)
Может кто знает, если способ проверить «валидность» doxygen документации?
Т.е. кто то поменял код, а документацию не обновил, например, после рефакторинга.
Т.е. кто то поменял код, а документацию не обновил, например, после рефакторинга.
Самая используемая мной директива — \todo, жаль, что Вы её не упомянули.) Позволяет удобно поддерживать список недоработок и отложенных задач в коде.
Хочу поделиться своим опытом. Возможно изобрел велосипед, но он был очень удобным)
Несколько лет назад использовал doxygen для документирования кода на С++ и API, но сгенерированный документ не устраивал. Необходимо было вставлять подробное описание некоторых процессов с графиками и диаграммами, большие блоки текста, таблиц и изображений, а также небольших примеров использования кода. И все это по ГОСТам с рамками. При этом хотелось иметь не очень большое описание классов, функций в исходниках. Все это тащить в исходный код мы не могли.
Очень удобным оказалось использовать xml файл doxygen'а. Написал плагин для ворда на С#. Его задачей был поиск в теле документа тегов вида [!function_name] [!class_name] и их замена на блок с документацией функции/класса из xml файла doxygen'а. Все это сохранялось в новый файл. Аналогично делал для LaTeX. Таким образом на выходе получали красивую pdf'ку, которая обновлялась при редактировании исходного кода. Общее описание могли править не программисты, а документация функций, классов бралась из исходников.
К сожалению, исходниками поделиться не смогу, отдали вместе с проектом. Но написать подобный плагин для ворда, LaTeX или html очень легко.
На мой взгляд у новых языков программирования система документации и тестирования должна поддерживаться на уровне стандарта языка. Прямо при создании парсера.
Несколько лет назад использовал doxygen для документирования кода на С++ и API, но сгенерированный документ не устраивал. Необходимо было вставлять подробное описание некоторых процессов с графиками и диаграммами, большие блоки текста, таблиц и изображений, а также небольших примеров использования кода. И все это по ГОСТам с рамками. При этом хотелось иметь не очень большое описание классов, функций в исходниках. Все это тащить в исходный код мы не могли.
Очень удобным оказалось использовать xml файл doxygen'а. Написал плагин для ворда на С#. Его задачей был поиск в теле документа тегов вида [!function_name] [!class_name] и их замена на блок с документацией функции/класса из xml файла doxygen'а. Все это сохранялось в новый файл. Аналогично делал для LaTeX. Таким образом на выходе получали красивую pdf'ку, которая обновлялась при редактировании исходного кода. Общее описание могли править не программисты, а документация функций, классов бралась из исходников.
К сожалению, исходниками поделиться не смогу, отдали вместе с проектом. Но написать подобный плагин для ворда, LaTeX или html очень легко.
На мой взгляд у новых языков программирования система документации и тестирования должна поддерживаться на уровне стандарта языка. Прямо при создании парсера.
Меня удивляет отсутствие красивых шаблонов для Doxygen при его то популярности. Дефолтный — слишком программистский.
Кратко об оформлении документации в Doxygen я написал в новой статье. Возможно, некоторые из приведенных там примеров могут вас заинтересовать.
В своё время для C# перешёл с Doxygen на Sandcastle. Сейчас проверил развитие Sandcastle на Codeplex остановилось в 2010, но нашёлся добрый человек, который сделал форк, выложил на GitHub и даже выпустил Help File Builder and Tools v2015.1.12.0.
Мне кажется, что документация должна писаться сама по себе, без строгой привязки к коду. По крайней мере, все что попадалось из серии «автогенерация по комментариям» было ужасным:
Опять же Doxygen заставляет учить свою разметку, вместо стандартной для многих Javadoc
- код было невозможно читать, т.к. через строку шли комментарии.
- документацию невозможно было читать, т.к. она собрана из кусочных комментариев кода, а не представляла собой отдельный рассказ с примерами и аргументами по архитектуре.
Опять же Doxygen заставляет учить свою разметку, вместо стандартной для многих Javadoc
Отдельно нужно писать гайды по использованию, а Class Reference documentation имеет смысл писать в коде: отпадает сложность синхронизации кода и документации + лёгкий доступ к информации из IDE.
Разметка Doxygen проста (если не пытаться делать сложных документов). Javadoc стандартна только для тех, кто использует Java, Doxygen, насколько я помню, появился, как аналог для других языков.
В корпоративной среде отдельную документацию сделать можно, но Doxygen прежде всего ориентирован на разработчиков свободного ПО, где несколько иные традиции. Одно дело вставить комментарии в код, и совсем другое — писать документацию. А ведь её ещё нужно поддерживать в актуальном состоянии.
В корпоративной среде отдельную документацию сделать можно, но Doxygen прежде всего ориентирован на разработчиков свободного ПО, где несколько иные традиции. Одно дело вставить комментарии в код, и совсем другое — писать документацию. А ведь её ещё нужно поддерживать в актуальном состоянии.
Doxygen — это ужасная система. Генерить сырой html при существующих стандартах веба для документации — это преступление. Не использовать синтаксические парсеры, вроде clang-ast, для контроля соответствия описания и реальных функций — это преступление. В общем-то, я бы рекоммендовал закопать пациента, но, увы, какой-то нормальной замены ему нет. Сам же колхозил нечто подобное с выводом в markdown без всяких мерзких html: github.com/vstakhov/doxydown Но по функционалу, конечно, до doxygen ему далеко. С другой стороны, для моих задач его хватает (например, так: rspamd.com/doc/lua/config.html).
Генерить сырой html при существующих стандартах веба для документации — это преступление.Можно подробнее про стандарты, а то быстро нагуглить не удалось?
Ну как, ваяешь ты, такой, статический сайтик на bootstrap + jekyll, все получается красиво, в едином стиле. Хочешь сгенерить документацию, и тут бах — привет из 90-х: html от doxygen. Конечно, те, кто познал дао css + html, допускаю, смогут из этого сделать что-то вменяемое (хотя в gnome, например, забили на это и тоже написали свой велосипед gtk-doc, который, к слову, выглядит заметно приятнее); но для обычного человека этот ужас никак уже не привести в единый вид с общим сайтом. Кроме того, документацию в markdown можно прямо с разметкой читать через github (https://github.com/vstakhov/libucl/blob/master/doc/lua_api.md).
Norserium А можно ли как-либо выносить примеры использования функции, которую документирую в отдельный файл? Хочется сделать комментарии по меньше и в doxygen-комментарии вставлять ссылку на файл с примером. Как такое сделать, если возможно вообще?
Выше в разделе «Код внутри документации» я писал про команду \snippet. Мне кажется, что это именно то, что вам нужно.
Приведу сразу пример из документации. Пусть в файле snippets/example.cpp у вас есть некоторый код, в нём вы выделяете пример при помощи документирующих блоков с указанием имени фрагмента.
Затем уже в документирующем блоке, в котором вы описываете вашу функцию, вы добавляете следующую команду:
В результате в документацию будет включен следующий код:
Если желаете, могу добавить пример в статью.
Приведу сразу пример из документации. Пусть в файле snippets/example.cpp у вас есть некоторый код, в нём вы выделяете пример при помощи документирующих блоков с указанием имени фрагмента.
QImage image(64, 64, QImage::Format_RGB32);
image.fill(qRgb(255, 160, 128));
//! [Adding a resource]
document->addResource(QTextDocument::ImageResource,
QUrl("mydata://image.png"), QVariant(image));
//! [Adding a resource]
...
Затем уже в документирующем блоке, в котором вы описываете вашу функцию, вы добавляете следующую команду:
\snippet snippets/example.cpp Adding a resource
В результате в документацию будет включен следующий код:
document->addResource(QTextDocument::ImageResource,
QUrl("mydata://image.png"), QVariant(image));
Если желаете, могу добавить пример в статью.
Да, ещё есть команда \example, которая позволяет добавить ссылку на пример в документируемый элемент (а также в отдельный список примеров, если он у вас создаётся).
Но в этом случае будет добавлена именно ссылка, а не вставлен код. Пример ниже:
Эту команду удобно использовать, когда код примера у вас большой. В случае, если же пример небольшой, на мой взгляд, предпочтительнее использовать непосредственную вставку кода (три способа для этого я описал в статье). Вообще, посмотреть в живую на пример использования этой команды можно здесь.
Но в этом случае будет добавлена именно ссылка, а не вставлен код. Пример ниже:
Эту команду удобно использовать, когда код примера у вас большой. В случае, если же пример небольшой, на мой взгляд, предпочтительнее использовать непосредственную вставку кода (три способа для этого я описал в статье). Вообще, посмотреть в живую на пример использования этой команды можно здесь.
А расскажите пожалуйста про генерацию диаграмм классов? Очень интересует этот вопрос.
dendibakh, продолжая традицию, я решил рассказать об этом отдельной статьёй. Приглашаю вас с ней ознакомиться.
UFO just landed and posted this here
r44083, я пошёл самым простым путём: поставил подсветку синтаксиса для языка, в котором символ для начала комментариев такой же, какой использует и Doxygen (да, это был старый-добрый Python).
Вообще, есть специальные пакеты для подсветки его синтаксиса (например, этот), но мне не приходилось ими пользоваться.
Вообще, есть специальные пакеты для подсветки его синтаксиса (например, этот), но мне не приходилось ими пользоваться.
Я бы хотел пояснить сложный код картинками. Пробую для этой цели doxygen. Нашел как вставить картинку, нашел как вставить исходник в документацию (INLINE_SOURCES). Но в документации получается, что в начале все комментарии и картинки, а потом исходник с вырезанными комментарии. Возможно ли сделать так, чтобы комментарии и картинки были расположены между строк исходника?
Насколько я понимаю, вам необходимо добавить в документацию к тем или иным документируемым элементам (например, функции) пояснение относительно того, как работает код внутри них?
Вполне возможно, вашу задачу можно решить путём использования команд \code и \endcode (о них я писал в статье), но вы уверены, что Doxygen подходящий инструмент для решения вашей задачи? Ведь основной его задачей является документация API, соответственно, функции и методы представляются по большей части как чёрные ящики. Можете убедиться в этом изучив примеры существующих документаций и того, что и как документируется в них.
Мне кажется, к тому, что вы ищите ближе тот же Docco.
Вполне возможно, вашу задачу можно решить путём использования команд \code и \endcode (о них я писал в статье), но вы уверены, что Doxygen подходящий инструмент для решения вашей задачи? Ведь основной его задачей является документация API, соответственно, функции и методы представляются по большей части как чёрные ящики. Можете убедиться в этом изучив примеры существующих документаций и того, что и как документируется в них.
Мне кажется, к тому, что вы ищите ближе тот же Docco.
Мне надо внутри функции комментировать линии и возле некоторых поставить имя картинки. И на выходе получить исходник с комментариями и картинками в каком-то формате (html, markdown без разницы), чтобы все это можно было нормально читать. Я так понял, \code и \endcode требуют скопировать всю функцию в комментарий, что дико неудобно.
> но вы уверены, что Doxygen подходящий инструмент для решения вашей задачи?
мне любой инструмент подойдет, который поможет, но doxygen имеет всякие полезные фичи, так что при прочих равных я бы предпочел его
> Docco
Эта штука для javascript? Просто мне для c++
> но вы уверены, что Doxygen подходящий инструмент для решения вашей задачи?
мне любой инструмент подойдет, который поможет, но doxygen имеет всякие полезные фичи, так что при прочих равных я бы предпочел его
> Docco
Эта штука для javascript? Просто мне для c++
Я так понял, \code и \endcode требуют скопировать всю функцию в комментарий, что дико неудобно.Это не так, воспринимайте эти команды как способ оформления текста. Вы можете разместить там абсолютно произвольный код, причём даже не имеющий отношения к вашей функции, и в любом объёме.
И, да, я убеждаюсь в том, что Doxygen не совсем подходящее решение для вас. Судя по сказанному, вам просто требуется преобразовать исходники в удобный для чтения формат, снабженный иллюстрациями, а не автоматически генерировать документацию для своего кода.
Эта штука для javascript? Просто мне для c++Нет, не только. Вот результат её работы для .cpp файла:
Код примера
Пример кода позаимствован отсюда
// В данном файле определена функция, которая возвращает n-е число Фибоначчи.
// Данная задача решается с помощью быстрого возведения матрицы в степень, что позволяет обеспечить быстрое вычисление искомого значения
int fib(int n)
{
int a = 1, ta,
b = 1, tb,
c = 1, rc = 0, tc,
d = 0, rd = 1;
while (n)
{
// Если степень нечетная, то умножаем вектор R на матрицу A
if (n & 1)
{
tc = rc;
rc = rc*a + rd*c;
rd = tc*b + rd*d;
}
// Затем умножаем матрицу A на саму себя
ta = a; tb = b; tc = c;
a = a*a + b*c;
b = ta*b + b*d;
c = c*ta + d*c;
d = tc*tb+ d*d;
n >>= 1;
}
return rc;
}
Пример кода позаимствован отсюда
В общем я нашел такую штуку, более чем удобно mariusbancila.ro/blog/2017/11/23/memeful-comments-extension-for-visual-studio
Где лучше писать документацию? В *.с или в *.h? Например если библиотека то лучше в хидере? Или и там и там для большего визуального восприятия.
Для Doxygen нет разницы, где будут размещены документирующие блоки. Так что в рамках каждого отдельного проекта на этот вопрос отвечают по-разному.
В связи с этим предлагаю ознакомиться со следующей дискуссией.
Мне лично пока нравится подход, при котором краткое описание (
В связи с этим предлагаю ознакомиться со следующей дискуссией.
Мне лично пока нравится подход, при котором краткое описание (
\brief, \param, \return и т.д.) указывается перед объявлением метода, а подробное описание (\detail) перед его определением. Такой подход, в частности, используется в µOS++.Sign up to leave a comment.
Документируем код эффективно при помощи Doxygen