что такое документация к коду
Документация как код: шесть принципов программирования, которые помогут создавать документы, понятные каждому
Авторизуйтесь
Документация как код: шесть принципов программирования, которые помогут создавать документы, понятные каждому
Рассказывает Дмитрий Толоконников, бизнес-аналитик департамента ИТ-аутсорсинга ALP Group
Больше пяти лет я занимаюсь бизнес-процессами. В особенности процессами технической поддержки, которую мы оказываем коммерческим и государственным компаниям. Например, я слежу, чтобы уровень качества IT-обслуживания соответствовал международным стандартам. Я программирую и работаю с документацией — пишу регламенты и процедуры, описываю процессы, выпускаю инструкции.
Всё это время я неосознанно «перетаскиваю» общие принципы программирования в работу с документами. Это помогает мне не делать бесполезные «спагетти-простыни» и писать внятные рабочие документы с ясной структурой, даже если документация очень объёмная и должна часто меняться в соответствии с изменениями в компании и все её части должны быть связаны воедино, чётко объяснять, как что-то работает. Возможно, мои приёмы помогут и вам.
Принципы работы с текстом
DRY — Don’t repeat yourself. Не повторяйся
Если вы вставили один и тот же блок в 10 разных регламентов и что-то меняете в нём, то у вас образуется 10 одинаковых мест, куда нужно внести одинаковые изменения. Вероятность забыть об этом тоже растёт, даже если вы пользуетесь бессмертным «Ctrl+C» — «Ctrl+V». Особенно в последней паре документов.
В программировании такие блоки выделяют в отдельные функции, классы, а в работе с документами повторяющиеся элементы нужно выносить в отдельные разделы или документы и давать ссылки на них.
KISS — Keep it simple, stupid. Не усложняй
Посмотрите вокруг: люди привыкли к простоте. Интуитивно понятные интерфейсы и всплывающие подсказки в приложениях. Принцип одного окна в IT-обслуживании. Засилье коротких статей и обучающих видео в Интернете. Той же простоты они ждут и от рабочих документов.
18–24 октября, Онлайн, Беcплатно
Этот принцип я обычно использую как маркер. Если описание процесса слишком сложное — нужно упростить процесс. Если инструкция к приложению слишком замысловатая — надо доработать приложение.
Обычно это проще и дешевле, чем писать сложную документацию, заставлять каждого нового сотрудника её читать, понимать и учиться действовать по ней. А ведь потом ещё нужно будет вносить изменения в документацию.
YAGNI — You ain’t gonna need it. Тебе это не понадобится
Это продолжение принципа KISS. Обычно я применяю его, когда собираюсь создать универсальное решение с заделом на будущее. Проблема в том, что такое решение — само по себе усложнение. Не факт, что в будущем оно понадобится. Обычно нет смысла создавать всеобъемлющее описание бизнес-процессов направления, которое только сформировалось и активно развивается. Практика показывает, что будущее внесёт серьёзные коррективы.
Но здесь важно разумно подходить к вопросу. Есть вещи, изменение которых дорого обходится. Их как раз нужно готовить с заделом на будущее. В программировании эту работу относят к архитектуре приложения, а в документации просто сразу говорят: «Это нам не понадобится». И в будущем с трудом навёрстывают упущенное.
Принципы работы со структурой
Чем объёмнее становится документация, тем сложнее поддерживать её актуальность. Изменение одного документа влечёт за собой каскадное изменение остальных, логическая целостность ломается, структура требует очередной переработки. К счастью, для программирования это стандартная проблема, и за прошедшие десятилетия выработались общие принципы написания легко поддерживаемого кода. Часть из них можно применять и к документам.
SRP — Single Responsibility Principle. Принцип единственной ответственности
Яркий маркер нарушения принципа — наличие побочных действий. Например, метод класса отвечает за отправку клиенту уведомления о новом заказе в интернет-магазине, но при этом ещё и обновляет текущий баланс клиента.
То же самое справедливо и для документации. Например, в регламент регистрации обращения клиента не нужно впихивать что-то «заодно»: принципы вежливого общения с клиентами, краткое описание self-service портала и т. д.
Нельзя рассчитывать, что такая информация будет усвоена или сотрудники запомнят, к какому документу нужно обращаться, чтобы её получить. Зато это запутывает документ, лишает структуру чёткости и требует дополнительного времени для актуализации. Если вы действительно хотите напомнить о вежливости при общении с клиентом, вставьте в регламент ссылку на соответствующий документ (вспомните о DRY).
Соблюдение принципа позволяет делать документы короче. Их название соответствует назначению, а чтение не вызывает неприятных сюрпризов. Их проще прочитать за раз. И не забыть, с чего документ начинался.
SLAP — Single Level of Abstraction Principle. Принцип единого уровня абстракции
Является логичным продолжением принципа единственной ответственности (SRP).
Применение принципов KISS и SRP побуждает писать небольшие, простые и понятные документы. Но эти документы нужно собрать в такую же простую и понятную структуру. Здесь помогает выделение и соблюдение уровней абстракций.
Например, очевидно, что нет смысла пытаться поместить в один огромный документ объёмную документацию вроде описания системы менеджмента качества. Намного логичнее разбить его на уровни абстракций и сделать для каждого уровня разные документы — верхнеуровневое описание системы, описание каждого процесса и т. д.
При этом важно соблюдать принцип единого уровня абстракций и относить информацию только к нужному уровню. Если вы пишете верхнеуровневое описание, не надо вдаваться в детали работы конкретного процесса. Не тот уровень абстракции! Оставьте эту информацию для описания процесса. Этот принцип дополняет SRP, заставляя автора контролировать не только то, за что отвечает документ, но и на каком уровне в иерархии он находится.
LoD — Law of Demeter (Don’t talk to strangers). Закон Деметры (Не разговаривай с незнакомцами)
Если применить закон к документации, то каждый документ:
Например, процесс управления IT-инцидентами взаимодействует с процессом управления проблемами напрямую, а с процессом управления изменениями — только через управление проблемами. Тогда в описании управления инцидентами можно ссылаться на описание управления проблемами. А вот ссылаться на описание управления изменениями не надо.
Итого
Указанные выше принципы сильно помогают мне при написании документации по процессам, в создании регламентов, процедур и инструкций. К сожалению, это лишь небольшая часть рекомендаций по управлению качеством кода, поэтому заинтересовавшимся рекомендую самостоятельно углубиться в тему. Из неё можно извлечь много полезного. При этом важно помнить, что эти принципы не являются законами. В Интернете много спорят об их правильном использовании и часто злоупотребляют ими. Поэтому, пожалуйста, не впадайте в крайности. И не забывайте о здравом смысле.
Хинт для программистов: если зарегистрируетесь на соревнования Huawei Cup, то бесплатно получите доступ к онлайн-школе для участников. Можно прокачаться по разным навыкам и выиграть призы в самом соревновании.
Перейти к регистрации
Как писать техническую документацию для программ на C#
Рано или поздно в жизни каждого разработчика наступает момент, когда он не понимает, как работает его код. Выясняем, что с этим делать.
Программисты часто сталкиваются с тем, что не могут прочитать код. Такое случается постоянно: когда только приходят в новый проект, когда проверяют код коллеги или — так бывает чаще всего — когда смотрят результат своей же работы. Чтобы этого избежать, нужно писать и читать документацию.
Разработчики имеют дело с двумя основными видами документации:
К сожалению, не все разработчики (практически никто) любят читать документацию. Любителей писать её и того меньше. Однако делать это очень важно, потому что сложно поддерживать проект без документации.
Пишет о разработке сайтов, в свободное время создает игры. Мечтает открыть свою студию и выпускать ламповые RPG.
Правила хорошего тона в составлении документации
Составляя документацию, стоит следовать определенным правилам — они помогают сделать ее более понятной.
1. Документация нужна не всегда
Если программа одноразовая, не стоит тратить время на написание пояснений. Например, если нужен небольшой скрипт, который будет написан за пять минут и использован 1-2 раза.
2. Документация нужна не везде
Также не нужно писать пояснения ко всему. Если код написан хорошо, то по названиям уже будет понятно, что это такое и зачем оно используется. Например, легко догадаться, что метод int Sum (int a, int b) возвращает результат сложения двух чисел.
Исключение можно сделать, если речь идет об API или фреймворке, которыми пользуются многие разработчики: они не всегда видят исходный код, но могут использовать классы и методы. Поэтому им важно иметь список доступных методов. В этом случае задокументировать всё нужно просто для галочки.
3. Документация должна быть точной
Очень важно уметь ясно выражать свои мысли. Нужно предельно точно описывать, что делает тот или иной фрагмент кода. Для этого стоит давать как можно более короткие определения. Например:
В этом фрагменте кода объем документации к классу и его свойству не превышает одного предложения. Этого достаточно, чтобы было понятно, что это такое и для чего его нужно использовать.
4. Документация должна быть сухой
Хотя канцеляризмов нужно избегать, писать надо максимально сухо и по делу. Никаких стихов, метафор, аналогий или шуток — всё это может быть забавным, но не добавляет ясности.
5. В документации не должно быть старого кода
Этот правило больше касается обычных комментариев, чем самой документации. Однако оно очень важное, поэтому приведено здесь.
Никогда не храните в коде старые методы и операторы, даже если они задокументированы. Если что-то не используется в текущий момент — это мусор, от которого нужно избавиться.
Если есть сомнения пригодится ли еще этот код, его лучше сохранить в системе контроля версий — именно для этого ее и придумали.
Дальше речь пойдет о том, как писать техническую документацию для программ на C#. Вся работа будет вестись в Visual Studio.
Где писать документацию в C#
Вариантов много. Например, можно сделать это в Word или Google Docs, тогда разработчики смогут скачивать файл из интернета. Некоторые хранят инструкции в печатном виде, но это плохой вариант, потому что документация быстро устаревает.
Лучший способ — писать всё прямо в коде программы. Тогда у каждого разработчика будет доступ к документации в любое время. Самый примитивный вариант — использовать комментарии.
В C# есть два вида комментариев. Однострочные:
Как сделать документацию к коду?
Простой 3 комментария
Есть две крайности, которых лучше избегать:
1. красивая и исчерпывающая документация требует колоссальных ресурсов на поддержку
2. сложно воспринимаемый код, без малейших подсказок с чего все начинается и чем заканчивается
Кстати, проектная работа, это не только документация к коду, это еще и свод правил, которые позволят архитектуре не расползтись кто в лес кто по дрова, а также сохранят стилистику написания кода для единообразия и легкой поддерживаемости кода.
Думаю, вышеописанные пукнты не вяжутся с JS, хоть и прекрасно работают в других средах (php, java etc).
На JS вообще очень сложно писать «правильно» и «хорошо»))
Согласен, JSDOC, юнит тесты и автоматическая документация прекрасно работают в JS, но это, имхо, вообще не тот язык, который следует использовать в таких приложениях.
На счет 2007-го, а разве в JS уже появилась статическая типизация, интерфейсы, приватные свойства?))
Да и в сто раз проще написать hhvm совместимый код на PHP+фрейме ежели использовать его. Выйдет и быстрее, и проще, и лучше.
Документирование кодовой базы. Зачем и как?
Введение
Недавно, на одном из митингов моей команды, была поднята проблема отсутствия документации внутри кода. Было решено назначить ответственного за ведение документации. Нужно было найти подходящие инструменты документирования, определить стиль и регламент, представить решение команде. Я решил, что возьму эту задачу на себя, так как для меня это особенно важный вопрос. Мне, как новому сотруднику, было довольно тяжело разобраться в уже существующем коде без документации, и упустить возможность повлиять на ее появление я просто не мог. В итоге, в процессе определения стандарта для нашей команды и появилась эта статья. Я подумал о том, здесь присутствуют довольно интересные мысли, поэтому решил поделиться ими здесь.
Дисклеймер
Так как я С++ разработчик, то и документирование кода я рассматриваю как документирование кода С++. Когда я говорю код, функция, метод или класс, я подразумеваю код, функцию, метод или класс на С++.
Зачем?
Здесь я приведу пару пунктов формата вопрос-ответ. Это те вопросы, которые я задавал себе сам и слышал от своих коллег, когда вставал вопрос документирования кода.
«Все и так знают наш код»
Это утверждение справедливо для разработчиков с большим опытом работы в компании, но никак не для тех, кто только включается в проект. Чем больше документации встретит новичок в коде, тем быстрее он сможет включиться в работу. 10 минут чтения документации лучше, чем 2 часа отладки кода.
«Этот код прост и не нуждается в документации»
Если такая мысль пришла вам в голову, обдумайте ее еще раз. Если подумать еще не помогло, посоветуйтесь со своими коллегами. Если ваш код не вызвал вопросов при одном только взгляде на него, то, возможно, комментирование кода действительно излишне (но это не точно). Этот пункт будет подробнее обсуждаться далее.
«Этим кодом больше никто пользоваться не будет»
Это неправда. Не использоваться он будет до поры до времени. В моей практике были моменты, когда я реализовывал то, что уже есть в нашей кодовой базе. Отсутствие документации и, соответственно, привычки искать существующие решения в ней, привели меня к дубликации кода.
Общие советы документирования
Приведите пример использования вашего кода
Оставьте названия функций/методов/классов, ткните в место, где используется ваш код. Если вы использовали какое-то популярное решение (паттерн), оставьте ссылку на материал по этой теме. Это поможет быстрее сориентироваться в коде. Понятно, что поиск в IDE даст вам ту же информацию, но иногда он бывает долгий, плюс таким образом вы сможете особенно выделить то место, где использование вашего кода продемонстрировано максимально явно.
Если решение нетривиально, расскажите о причинах такого решения
Почему использовано именно такое решение? Порой приходится много времени заниматься отладкой и изучением кода, чтобы понять, почему коллега выбрал именно такой подход. Краткий ответ на вопросы зачем и почему сэкономит много времени. Данный пункт переплетается с первым.
Постарайтесь найти середину между отсутствием документации и документированием каждой строки
Не нужно писать целую поэму для метода, из названия которого понятно, что он делает (я надеюсь, что название соответствует тому, что он делает). Также не стоит думать, что, например, простой класс не нуждается в подробной документации. Здесь важно найти золотую середину.
Не пересказывайте код
Не превращайте ваши комментарии в это
Пример того, как делать не надо
Не забывайте о поддержке документации IDE
Сейчас почти все IDE способны выводить описание класса/метода/функции при взаимодействии с ним (наведение мыши, комбинация клавиш), если описание оформлено в нужном формате. Пишите документацию так, чтобы (1) IDE смогла ее «подхватить», (2) можно было обойтись чтением документации и избежать необходимости открывать код с целью его изучения.
Дайте описание поведения вашей функции/метода в случае ошибки
Что вернет ваш код? Возможны ли исключения и какие? Если функция бросает слишком много исключений, возможно не стоит перечислять их все.
Помните о том, что ваши комментарии в будущем будут читать другие люди, в том числе и вы
Не пишите документацию ради документации, пишите ее ради облегчения работы своей команды. Задайте себе вопрос: пойму ли я, что делает этот код, через месяц, посмотреть на комментарии? Для более честного ответа, попросите ответить на этот вопрос своих коллег.
Не забывайте об актуальности документации
Неактуальная информация уже неактуальна хуже ее отсутствия.
Вопросы о грамотности, удобстве, понятности документации и прочие популярные я опускаю с надеждой на то, что такие вещи для читателя само собой разумеющееся.
Документирование можно вести в стандарте JavaDoc. Это удобный формат, который знаком многим IDE и поддерживается Doxygenом. Плюсом для нас было то, что он уже частично используется в нашем проекте, и IDE, в которых мы работаем (CLion, QtCreator, VisualStudio) прямо поддерживают генерацию комментариев в этом стандарте и их отображение.
Далее будут описаны инструменты документации и некоторые правила, которые мы приняли в своей команде.
Многострочные и однострочные комментарии
Doxygen поддерживает много видов комментариев. Для нашей команды я выделил такие:
Хочу обратить внимание, что
Также существует такой вид комментария:
Такой вариант удобен, когда нужно задокументировать одну строку внутри функции, или дать описание переменной или члену класса/метода. Обратите внимание, что между слэшем и стрелкой нет пробела.
Команды
В JavaDoc есть так называемые команды. Команды служат для детализации, выделения документации. Команд в JavaDoc довольно много, плюс можно вводить свои. Те команды, которые используем мы, я опишу далее. К сожалению, многие команды (почти все) в C++ не поддерживаются так, как хотелось бы (так, как это сделано в Java). Но тем не менее это отличный способ структурировать вашу документацию, обеспечить удобство при чтении и поддержку Doxygen. Я настоятельно рекомендую пользоваться командами.
Классы, структуры, перечисления, области видимости
Документация должна находиться строго до объявления/описания кода. Это позволит нашим IDE, и в дальнейшем Doxygenу, подхватить комментарии.
Мы документируем такой код многострочным комментарием, даже если описание влезает в одну строку.
Это позволяет комментариям не выбиваться из общего стиля документирования. Комментарии в одну строку блочного кода должны быть редкостью!
Для указания краткого описания может быть использована команда @brief. Указанный после команды текст, вплоть до конца параграфа, будет относиться к краткому описанию, и для отделения от основного используется пустая строка.
Также можно (и даже нужно) добавлять команду @example. Такой вариант позволит быстрее найти пример использования кода.
Это отличный вариант соблюдения 2 пункта из советов.
Документация функций/методов
Функции и методы также должны документироваться строго над объявлением/описанием. Здесь я также выступаю за многострочные комментарии по тем же причинам, что и выше.
int sum(int a, int b)
Опишите поведение функции/метода в случае ошибки (что возвращает, какие исключения кидает). Для этого можно использовать команду @throw.
Документация членов в классе/структуре, переменных в функции, значений в перечислениях
Для таких объектов будет удобен такой стиль документации:
Или на крайний случай
Документируйте переменные однострочными комментариями, старайтесь уместить комментарий в одну строку. Там, где это невозможно, используйте многострочные комментарии.
Более подробно о технических деталях документации рассказано тут.
Как обеспечить качественную документацию?
Доверить ревью новичку даст два больших плюса:
В перспективе вы получите:
Подробную и качественную документацию
Более быстрый рост и включение в проект своих новых сотрудников
Резюме
Понятно, что все, о чем я рассказал выше, «хорошо только на бумаге». Вероятней всего, на практике вы столкнетесь с трудностями: негодование ваших коллег/сотрудников о «бесполезной» работе, «бедной» документации, несогласия о стиле. Но не мне вам говорить, что такие изменения никогда не даются легко:) Грамотный подход к решению вопроса документации в перспективе окупит себя.
Ссылки, которые помогли мне к подготовке данного материала:
Документируем код эффективно при помощи Doxygen
Данная статья входит в получившийся цикл статей о системе документирования Doxygen:
В этой статье мы сначала познакомимся с самой системой и её возможностями, затем разберёмся с её установкой и базовыми принципами работы, и, наконец, завершим знакомство рассмотрением различных примеров документации, примеров того, как следует документировать те или иные части кода. Словом, познакомимся со всем тем, что позволит вам освоиться и начать работать с этой замечательной системой.
Введение
Вероятнее всего, каждый из нас сталкивался с результатами работы различных генераторов документации. Общий принцип их работы следующий: на вход такого генератора поступает специальным образом комментированный исходный код, а иногда и другие компоненты программы, а на выходе создаётся готовая документация для распространения и использования.
Рассматриваемая система Doxygen как раз и выполняет эту задачу: она позволяет генерировать на основе исходного кода, содержащего комментарии специального вида, красивую и удобную документацию, содержащую в себе ссылки, диаграммы классов, вызовов и т.п. в различных форматах: HTML, LaTeX, CHM, RTF, PostScript, PDF, man-страницы.
Впрочем, следуя сложившейся традиции, в примерах я буду использовать C++, однако это не должно смущать вас, если вы предпочитаете другой поддерживаемый язык, поскольку особой разницы на практике вы даже не заметите, и большинство сказанного далее будет справедливо и для вашего языка.
К слову, список проектов, использующих Doxygen имеется на официальном сайте, причём большинство из этих проектов свободные. Поэтому желающие могут скачать исходник того или иного проекта и посмотреть как там разработчики осуществляли документацию.
Установка и настройка
Скачать последнюю версию Doxygen можно на официальном сайте, дистрибутивы которой доступны для большинства популярных операционных систем, кроме того, вы можете воспользоваться вашим пакетным менеджером. Помимо этого для комфортной и полнофункциональной работы рекомендуется установить Graphviz.
Далее работа с Doxygen весьма тривиальна: достаточно запустить программу, указав ей путь к файлу с настройками.
Но в этом файле и вся тонкость. Дело в том, что каждому проекту соответствует свой файл настроек, в котором может быть прописан путь до исходников проекта, путь, по которому должна быть создана документация, а также большое число других разнообразных опций, которые подробно описаны в документации, и которые позволяют максимально настроить документацию проекта под свои нужды.
В принципе, для редактирования данного файла и, вообще, работой с Doxygen, можно воспользоваться программой Doxywizard, которая чаще всего идёт вместе с Doxygen и которая позволяет чуть удобнее работать с файлом настроек (слева – Doxywizard; справа – файл открытый в текстовом редакторе):
Итак, приступим к созданию файла с настройками. Вообще, если вы используете Doxywizard, то он будет создан автоматически, в противном случае для создания этого файла необходимо запустить программу Doxygen с ключом -g (от generate):
Рассмотрим основные опции, которые могут вам пригодится, чтобы создать первую вашу документацию:
| Тэг | Назначение | По умолчанию |
| DOXYFILE_ENCODING | Кодировка, которая используется для всех символов в данном файле настроек | UTF-8 |
| OUTPUT_LANGUAGE | Устанавливает язык, на котором будет сгенерирована документация | English |
| PROJECT_NAME | Название проекта, которое может представлять собой единое слово или последовательность слов (если вы редактируете вне Doxywizard, последовательность слов необходимо поместить в двойные кавычки) | My Project |
| PROJECT_NUMBER | Данный тэг может быть использован для указания номера проекта или его версии | — |
| PROJECT_BRIEF | Краткое однострочное описание проекта, которое размещается сверху каждой страницы и даёт общее представление о назначении проекта | — |
| OUTPUT_DIRECTORY | Абсолютный или относительный путь, по которому будет сгенерирована документация | Текущая директория |
| INPUT | Список файлов и/или директорий, разделенных пробелом, которые содержат в себе исходные коды проекта | Текущая директория |
| RECURSIVE | Используется в том случае, если необходимо сканировать исходные коды в подпапках указанных директорий | NO |
После того, как мы внесли необходимые изменения в файл с настройками (например, изменили язык, названия проекта и т.п.) необходимо сгенерировать документацию.
Для её генерации можно воспользоваться Doxywizard (для этого необходимо указать рабочую директорию, из которой будут браться исходные коды, перейти на вкладку «Run» и нажать «Run doxygen») или запустив программу Doxygen, указав ей в качестве параметра путь к файлу с настройками:
Основы документирования на Doxygen
Теперь, когда мы разобрались с тем, как настраивать Doxygen и работать с ним, впору разобраться с тем, как необходимо документировать код, основными принципами и подходами.
Сразу отметим, что, вообще, всего существует два основных типа документирующих блоков: многострочный блок и однострочный блок.
Разница между ними чуть более сильная, чем между однострочным и многострочным комментарием. Дело в том, что текст, написанный в однострочном блоке относится к краткому описанию документируемого элемента (сродни заголовку), а текст, написанный в многострочном блоке относится к подробному описанию. Про эту разницу не следует забывать.
Многострочный блок
Мы сказали, что любой блок – это комментарий, оформленный специальным образом. Поэтому необходимо определить каким таким «специальным образом». Вообще, существует целый ряд способов для описания многострочного блока, и выбор конкретного способа зависит от ваших предпочтений:
При этом звездочки не обязательно ставить на каждой строке. Такая запись будет эквивалентной:
Сказанное о необязательности промежуточных звездочек также остаётся справедливым. Помимо названных двух стилей есть ещё ряд, но на них пока мы не будем останавливаться.
При этом ещё раз обратите внимание на то, что текст написанный в таком комментарии относится к подробному описанию.
Для указания краткого описания может быть использована команда \brief. Указанный после команды текст, вплоть до конца параграфа будет относится к краткому описания, и для отделения подробного описания и краткого описания используется пустая строка.
Однострочный блок
Для описания однострочного блока опять же существует целый ряд способов оформления, рассмотрим два из них:
При этом хотелось бы обратить внимание на два момента:
Например следующие два способа документирования дадут один и тот же результат:
Да, Doxygen крайне гибок в плане способов документирования, однако не стоит этим злоупотреблять, и в рамках одного проекта всегда придерживайтесь заранее оговоренного единообразного стиля
Размещение документирующего блока после элемента
Во всех предыдущих примерах подразумевалось, что документирующий блок предварял документируемый элемент, но иногда бывают ситуации, когда удобнее разместить его после документируемого элемента. Для этого необходимо в блок добавить маркер «
Кроме того, обратите внимание на то, что вы можете создавать и собственные команды. Подробно об этом можно прочитать в соответствующем разделе документации.
Документирование основных элементов исходного кода
Теперь мы можем рассмотреть специфичные особенности документирования различных элементов исходного кода, начиная от файлов в целом и заканчивая классами, структурами, функциями и методами.
Документирование файла
Хорошей практикой является добавление в начало файла документирующего блока, описывающегося его назначение. Для того, чтобы указать, что данный блок относится к файлу необходимо воспользоваться командой \file (причём в качестве параметра можно указать путь к файлу, к которому относится данный блок, но по умолчанию выбирается тот файл, в который блок добавляется, что, как правило, соответствует нашим нуждам).
Документирование функций и методов
При документировании функций и методов чаще всего необходимо указать входные параметры, возвращаемое функцией значение, а также возможные исключения. Рассмотрим последовательно соответствующие команды.
Параметры
Для указания параметров необходимо использовать команду \param для каждого из параметров функции, при этом синтаксис команды имеет следующий вид:
В результате мы получим такую вот аккуратную документацию функции:
Возвращаемое значение
Для описание возвращаемого значения используется команда \return (или её аналог \returns). Её синтаксис имеет следующий вид:
Рассмотрим пример с описанием возвращаемого значения (при этом обратите внимание на то, что параметры описываются при помощи одной команды и в результате они в описании размещаются вместе):
Получаем следующий результат:
Исключения
Для указания исключения используется команда \throw (или её синонимы: \throws, \exception), которая имеет следующий формат:
Простейший пример приведён ниже:
Документирование классов
Классы также могут быть задокументированы просто предварением их документирующим блоком. При этом огромное количество информации Doxygen получает автоматически, учитывая синтаксис языка, поэтому задача документирования классов значительно упрощается. Так при документировании Doxygen автоматические определяет методы и члены класса, уровни доступа к функциям, дружественные функции и т.п.
Если ваш язык не поддерживает явным образом определенные концепции, такие как например уровни доступа или создание методов, но их наличие подразумевается и его хотелось бы как-то выделить в документации, то существует ряд команд (например, \public, \private, \protected, \memberof), которые позволяют указать явно о них Doxygen.
Документирование перечислений
Документирование перечислений не сильно отличается от документирования других элементов. Рассмотрим пример, в котором иллюстрируется то, как можно удобно документировать их:
То есть описание состояний указывается, собственно, после них самих при помощи краткого или подробного описания (в данном случае роли это не играет).
Результат будет иметь следующий вид:
Модули
Отдельное внимание следует обратить на создание модулей в документации, поскольку это один из наиболее удобных способов навигации по ней и действенный инструмент её структуризации. Пример хорошей группировки по модулям можете посмотреть здесь.
Далее мы кратко рассмотрим основные моменты и приведём пример, однако если вы хотите разобраться во всех тонкостях, то тогда придётся обратиться к соответствующему разделу документации.
Создание модуля
Для объявления модуля рекомендуется использовать команду \defgroup, которую необходимо заключить в документирующий блок:
Идентификатор модуля представляет собой уникальное слово, написанное на латинице, который впоследствии будет использован для обращения к данному модулю; заголовок модуля – это произвольное слово или предложение (желательно краткое) которое будет отображаться в документации.
Обратите внимание на то, что при описании модуля можно дополнить его кратким и подробным описанием, что позволяет раскрыть назначение того или иного модуля, например:
Размещение документируемого элемента в модуле
Для того, чтобы отнести тот или иной документируемый элемент в модуль, существуют два подхода.
Первый подход – это использование команды \ingroup:
Его недостатком является то, что данную команду надо добавлять в документирующие блоки каждого элемента исходного кода, поскольку их в рамках одного модуля может быть достаточно много.
Поэтому возникает необходимость в другом подходе, и второй подход состоит в использовании команд начала и конца группы: @ <и @>. Следует отметить, что они используются наряду с командами \defgroup, \addtogroup и \weakgroup.
Пример использования приведён ниже:
Смысл примера должен быть понятен: мы объявляем модуль, а затем добавляем к ней определенные документируемые элементы, которые обрамляются при помощи символов начала и конца модуля.
Однако, модуль должен определяться один раз, причём это объявление будет только в одном файле, а часто бывает так, что элементы одного модуля разнесены по разным файлым и потому возникает необходимость использования команды \addtogroup, которая не переопределяет группу, а добавляет к ней тот или иной элемент:
Название модуля указывать необязательно. Дело в том, что данная команда может быть использована как аналог команды \defgroup, и если соответствующий модуль не был определена, то она будет создана с соответствующим названием и идентификатором.
Наконец, команда \weakgroup аналогична команде \addtogroup, отличие заключается в том, что она просто имеет меньший приоритет по сравнению с ней в случае если возникают конфликты, связанные с назначение одного и того же элемента к разным модулям.
Создание подмодуля
Для создания подмодуля достаточно при его определении отнести его к тому или иному подмодулю, подобно любому другому документируемому элементу.
Пример приведён ниже:
Пример создания нескольких модулей
Обратите внимание на то, что вид документирующих блоков несколько изменился по сравнению с приведёнными ранее примерами, но как мы говорили ранее, принципиального значения это не играет и выбирайте тот вариант, который вам ближе.
В результате мы получим следующую документацию:
Оформления текста документации
Теперь, после того, как мы в общих чертах разобрались с тем как документировать основные элементы кода, рассмотрим то, как можно сделать документацию более наглядной, выразительной и полной.
Код внутри документации
Зачастую внутри пояснения к документации необходимо для примера добавить какой-то код, например для иллюстрации работы функции.
Команды \code и \endcode
Один из наиболее простых и универсальных способов сделать это – команды \code и \endcode, которые применяются следующим образом:
Используемый язык определяется автоматически в зависимости от расширения файла, в котором располагается документирующий блок, однако в случае, если такое поведение не соответствует ожиданиям расширение можно указать явно.
Рассмотрим пример использования:
Результат будет иметь следующий вид:
Примеры кода
Иногда удобнее приводить примеры использования кода хранить в отдельных файлах. Для этого эти файлы необходимо разместить в отдельной директории и прописать к ней путь в настройках:
Рассмотрим, некоторые способы того, как примеры кода могут быть использованы в документации.
Команда \example
Данная команда показывает, что документирующий блок относится к примеру кода.
Текст исходного кода будет добавлен в раздел «примеры», а исходный код примера будет проверен на наличие документированных элементов, и если таковые будут найдены, то к ним в описание будет добавлена ссылка на пример.
В данном примере, значение EXAMPLE_PATH = examples
Команда \include
Для того, чтобы добавить в описание к документируемому элементу код примера используется команда \include, общий формат которой имеет следующий вид:
Она полностью копирует содержимое файла и вставляет его в документацию как блок кода (аналогично оформлению кода в блок начинающийся командой \code и заканчивающийся командой \endcode).
Команда \snippet
Команда \snippet аналогична предыдущей команде, однако она позволяет вставлять не весь файл, а его определенный фрагмент. Неудивительно, что её формат несколько другой:
Для выделения определенного фрагмента кода необходимо в начале и в конце его разместить документирующий блок с указанием имени фрагмента:
Автоматическое внедрение кода документируемого объекта
Наконец, Doxygen поддерживает возможность автоматической вставки тела функций, методов, классов, структур и т.п., в их подробное описание. Для этого используется следующая опция:
Формулы с использованием LaTeX
Doxygen позволяет использовать TeX формулы прямо в документации, это очень удобно и результат получается весьма достойным. Однако стоит отметить, что при этом имеются ограничения: на данный момент формулы могут быть вставлены только в HTML и LaTeX документацию, но этого, как правило, вполне достаточно.
На данный момент существует два подхода к отображению формул:
Способы добавление формул в документацию
Существуют три способа добавления формул в документацию. Последовательно рассмотрим каждый из них с примерами из документации:
Результатом будет строка следующего вида: расстояние между и равно
Результатом будет строка следующего вида:
В итоге мы получим следующий результат (заметим, что окружение eqnarray* – это ненумерованное окружение для размещения нескольких формул):
Пример внедрения формул в документацию
Рассмотрим конкретный пример документации с использованием формул LaTeX:
Результат представлен ниже:
Кратко о Markdown
Markdown – это облегчённый язык разметки (почитать о нём можно, например, здесь, а также в специальном разделе в документации). Начиная с версии 1.8.0. Doxygen обеспечивает его пока ограниченную поддержку и он служит одним из способов оформить документацию (альтернативой могут быть, например, команды для оформления документации или HTML вставки, которые, впрочем, не универсальны).
Не хотелось бы сейчас расписывать подробности и принципы данного языка, поэтому ограничимся рассмотрением того, как данный язык позволяет «украсить» нашу документацию:
Результат представлен ниже:
Подводя итоги
На этой ироничной ноте я решил остановиться. Я прекрасно понимаю, что ещё многое не было описано и затронуто, но, надеюсь, что главные свои цели статья выполнила: познакомить с понятием генератора документации, познакомиться с системой Doxygen, объяснить основные принципы и подходы к документации, а также мельком затронуть вопросы, связанные с её оформление и детализацией, подготовив задел для вашей дальнейшей работы.