Что такое Doc As Code

Как нетрудно догадаться, Doc As Code призывает оформлять документацию проекта в привычном для программиста виде - как код. В этом случае мы можем использовать систему контроля версий для хранения и управления документацией со всеми вытекающими. Подробнее о Doc As Code можно почитать здесь, а мы перейдем непосредственно к практике и рассмотрим один из способов организации документации проекта на C++.

Состав документации

Глобально выделим две составляющих документации проекта:

техническая документация (technical overview): включает проектную документацию, руководства разработчика, руководства пользователя и т.п.
описание сущностей (reference manual): включает документацию API, классов, структур, функций и т.д.

Инструменты

Описание сущностей уже само по себе располагается прямо в исходном коде. Классы и методы описываются либо в заголовочных файлах .h, либо в их реализации .cpp. Для работы с этим типом документации будем использовать Doxygen. Doxygen позволяет оформлять документацию исходного кода в разных стилях (Javadoc, Qt-style и др.) и предоставляет инструменты для генерации ее пользовательского представления. Например, HTML-документ.

Техническую документацию оформим в формате Markdown. Это простой текстовый формат разметки документов. Markdown используется, например, в Вики на платформах GitHub/GitLab. Если ваш проект размещается на платформе с поддержкой Вики, ее и используйте. Мы же рассмотрим ведение всей документации проекта в пределах одного репозитория.

Современные среды разработки как правило поддерживают работу с Markdown из коробки. Для работы с документацией даже не обязательно выходить из любимой IDE. Например, Visual Code поддерживает реал-тайм предпросмотр для Markdown-файлов.

Используя возможности Doxygen по встраиванию Markdown-файлов, мы создадим единую HTML-документацию с технической частью и описанием сущностей.

Структура файлов проекта

Рассмотрим типовой проект библиотеки C++ с набором тестов. Файлы технической документации разместим в папке Doc в корне репозитория. На блоке ниже показана типовая структура файлов проекта, содержащая файл конфигурации Doxygen и папку Doc с Markdown-файлами:

Library
|---Readme.md
|---Doxygen                <----- Конфигурационный файл Doxygen
|---CMakeLists.txt
|---Lib
|   |---CMakeLists.txt
|   |---Lib.h
|   |---sources...
|---Tests
|   |---CMakeLists.txt
|   |---test sources...
|---Doc                    <----- Папка с Markdown-файлами
    |---Main.md
    |---Getting_Started.md
    |---other md-files...

В папке Doc разместим обязательный файл Main.md, определяющий главную страницу HTML-документации.

Конфигурационный файл Doxygen

Doxygen генерирует документацию на основе параметров, определенных в конфигурационном файле. Среди прочих параметров конфигурации Doxygen, рассмотрим наиболее интересные в нашем контексте.

Для начала генерируем шаблонный файл конфигурации:

doxygen -g Doxygen

Полученный файл содержит все возможные параметры. У некоторых даже проставлены значения. Каждый параметр сопровождается подробной справкой. Удобно. Мы же обратим внимание на эти:

Параметр	Описание
PROJECT_NAME	Название проекта. Будет отображаться в HTML-документе.
OUTPUT_DIRECTORY	Путь к сгенерированным файлам. Желательно указать какое-то осмысленное имя конечной папки.
MARKDOWN_SUPPORT	Поддержка Markdown. По умолчанию включена, делать ничего не надо.
INPUT	Содержит папки и файлы, для которых будет генерироваться документация. Можно оставить пустым или указать ".", что будет значить генерацию для всех папок проекта.
FILE_PATTERNS	Шаблоны имен, по которым нужно искать файлы для обработки. В нашем случае нужны заголовочные файлы .h и Markdown-файлы .md.
RECURSIVE	Включаем, чтобы Doxygen заходил во вложенные папки.
EXCLUDE_PATTERNS	Шаблоны имен файлов или папок, которые Doxygen должен пропустить.
USE_MDFILE_AS_MAINPAGE	Указываем Markdown-файл, который будет использоваться как главная страница документации. У нас это Main.md.

Пример заполнения рассмотренных полей:

...
PROJECT_NAME           = "Library"
OUTPUT_DIRECTORY       = LibraryReferenceDocumentation
MARKDOWN_SUPPORT       = YES
INPUT                  = .
FILE_PATTERNS          = *.h \
                         *.md
RECURSIVE              = YES
USE_MDFILE_AS_MAINPAGE = Doc/Main.md
...

Документация исходного кода

Правила оформления документации исходного кода хорошо отражены в документации Doxygen, а также в многочисленных материалах в Сети. Поэтому рассмотрим лишь небольшой пример для класса нашей импровизированной библиотеки Lib:

/**
 * @brief The Lib class defines a super library object.
 */
class Lib
{
public:
  /**
   * @brief Constructor.
   * 
   * @param arg the super argument
   */
  Lib(int arg);
};

Теперь запустим Doxygen, подав ему на вход наш конфигурационный файл:

doxygen Doxygen

Полученная документация класса Lib будет выглядеть так:

Особенности оформления Markdown

Как указано выше, главную страницу HTML-документации будет определять файл Main.md. Doxygen поддерживает Markdown, поэтому значимых проблем с разметкой быть не должно.

Файл Main.md обычно содержит приветственную информацию и ссылки на другие Markdown-файлы документации. Ссылки нужно указывать прямо на .md файлы относительно папки файла Main.md.

Рассмотрим небольшой пример Main.md:

# Library

Welcome to Library documentation!

[Getting Started](Getting_Started.md)

Тогда главная страница HTML-документации будет выглядеть так:

В файле Getting_Started.md размещаем руководство по быстрому старту работы с нашей библиотекой:

# Getting started

Just build the Lib!

Вывод

Doc As Code в связке с Doxygen / Markdown - это отличный способ организовать документацию проекта на С++. Вся документация размещается в репозитории рядом с исходным кодом. Для небольших проектов этого более чем достаточно.

Телеграм: Так себе программист.

ATrotsenko