Создаем документацию для библиотеки C++ с помощью Doxygen

Одним из этапов разработки любой программы или библиотеки на C++ является создание документации. В зависимости от проекта этот процесс может отнимать большое количество сил и времени.

Чтобы облегчить создание документации был создан Doxygen. Добавляя в код своего проекта комментарии, использующие особую нотацию в формате Doxygen, вы не только делаете код понятнее, но и после сборки, получаете документацию в формате html, а при желании и в PDF.

Сегодня мы рассмотрим создание документации для библиотеки C++ с помощью Doxygen.

Подготовка проекта

Мы будем использовать проект из git-репозитория:

cd c:\projects
git clone https://gitflic.ru/project/vasiliyaltunin/articles_blog_altuninvv_ru.git --depth 1

Если папка

c:\project\colorconsolelib

уже существует, просто удалите, либо переместите её!

Скопируем папку с проектом:

xcopy /y/e .\articles_blog_altuninvv_ru\qt6\libcolorconsole\colorconsolelib\ .\colorconsolelib\

Установка Doxygen

Откроем консоль Msys2 и введем:

pacman -S  mingw-w64-x86_64-doxygen mingw-w64-x86_64-graphviz

Обратите внимание мы устанавливаем именно

 mingw-w64-x86_64-doxygen

Это важно для того, чтобы CMake смог получить доступ к утилите при последующей сборке!

Проверим что doxygen установился. Из консоли введем:

doxygen –v
1.14.0

Всё установлено корректно.

Откроем папку с проектом и создадим папку для документации:
cd c:\projects\colorconsolelib
mkdir docs

Перейдем в папку и создадим базовый файл конфигурации Doxygen. Из консоли cmd введем:

cd docs
doxygen -g

Configuration file 'Doxyfile' created.

Now edit the configuration file and enter

  doxygen

to generate the documentation for your project

Проверим содержимое папки:

dir /w c:\projects\colorconsolelib\docs

[.]        [..]       Doxyfile

Был создан файл Doxyfile

Откроем проект библиотеки в VSCode

cd c:\projects\colorconsolelib
code .

Изменим содержимое файла

docs\Doxyfile

Заменим на:

# Doxyfile 1.14.0

#---------------------------------------------------------------------------
# Настройки проекта
#---------------------------------------------------------------------------

# Кодировка
DOXYFILE_ENCODING     = UTF-8

# Название проекта
PROJECT_NAME           = "Color Console Library"

# The PROJECT_NUMBER tag can be used to enter a project or revision number. This
# could be handy for archiving the generated documentation or if some version
# control system is used.

# Версия проекта, должна совпадать с версией в файле CMakeFiles.txt
# в строке
# VERSION 0.1.0
PROJECT_NUMBER        = "0.1.0"

# Краткое описание проекта
PROJECT_BRIEF         = "С помощью этой библиотеки можно выводить цветной текст в консоль Windows"

# Лого проекта мы не будем использовать логотип
PROJECT_LOGO          = ""

# Иконка проекта мы не будем использовать её
PROJECT_ICON          = ""

# Задаем каталог с исходным текстом из которого doxygen будет брать файлы
INPUT                 = ../ \ 
                        ../README.md

# Указываем какое файлы нужно документировать
FILE_PATTERNS         = *.cpp \
                        *.h 

# Указываем doxygen автоматически просматривать подкаталоги в поисках файлов
RECURSIVE             = YES

# Указываем doxygen исключить из обработки папки, которые не нужно обрабатывать
# На так же не нужно, чтобы внутренние заголовки библиотеки документировались
EXCLUDE               = ../cmake ../build ../src/colorconsole.h

# Как правило мы исключаем все папки с тестами из документации, и хотя тестов у нас 
# пока что нет, мы все равно пропишем не будущее
EXCLUDE_PATTERNS      = */test/*

# Эта опция указывает использовать файл README.md как главную страницу нашей 
# документации, мы создадим его позже
USE_MDFILE_AS_MAINPAGE = "../README.md"

# Нам не нужен вывод в формате LATEX
GENERATE_LATEX        = NO

# Вырезаем полные пути из документации, в противном случае у нас в документации будут 
# длинные пути к файлам, например:
# /c/projects/colorconsolelib/include/colorconsole/colorconsole.h
FULL_PATH_NAMES = NO

# Задаем язык нашей документации
OUTPUT_LANGUAGE = Russian

Мы оставили только нужные нам опции. На самом деле опций просто огромное количество, но не все их обязательно прописывать. В случае их отсутствия Doxygen будет использовать параметры по умолчанию.

Сохраним файл, перейдем в папку docs и запустим:

cd c:\projects\colorconsolelib\docs
doxygen

Doxygen version used: 1.14.0
Searching for include files...
Searching for example files...
Searching for images...
…
Generating concept documentation...
Generating module documentation...
Generating namespace documentation...
…
type lookup cache used 2/65536 hits=28 misses=2
symbol lookup cache used 59/65536 hits=131 misses=59
finished...

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

Создаем файл README.md для библиотеки C++

Создадим файл README.md:

cd c:\projects\colorconsolelib
type nul > README.md

Добавим для него содержимое:

**ColorConsole** библиотека позволяющая выводить цветной текст в консоль.

**Содержание :**
- [1. Описание библиотеки](#1-описание-библиотеки)
  - [1.1. Возможности](#11-возможности)
  - [1.2. Поддерживаемые платформы](#12-поддерживаемые-платформы)
    - [1.2.1. Статус поддержки](#121-статус-поддержки)
- [2. Требования](#2-требования)
  - [2.1. Стандарты C++](#21-стандарты-c)
  - [2.2. Зависимости](#22-зависимости)
- [3. Как собрать библиотеку](#3-как-собрать-библиотеку)
  - [3.1. Использование CMake](#31-использование-cmake)
  - [3.1.1. Встраиваемая библиотека](#311-встраиваемая-библиотека)
  - [3.1.1. Статическая и разделяемая библиотеки](#311-статическая-и-разделяемая-библиотеки)
  - [3.2. Опции CMake](#32-опции-cmake)
- [4. Как использовать библиотеку](#4-как-использовать-библиотеку)
  - [4.1. Использование](#41-использование)
  - [4.2. Версии библиотеки](#42-версии-библиотеки)
    - [4.2.1. Совместимость](#421-совместимость)
- [5. Документация](#5-документация)
- [6. Лицензия](#6-лицензия)


# 1. Описание библиотеки
## 1.1. Возможности

- Вывод цветного текста в консоль Windows
- Изменение фона текста
- Сброс фона до настроек по умолчанию

## 1.2. Поддерживаемые платформы
### 1.2.1. Статус поддержки

- Windows - поддерживается Windows 10
- Linux - в настоящий момент не поддерживается

# 2. Требования
## 2.1. Стандарты C++

Библиотека поддерживает стандарт **C++ 17** и выше

## 2.2. Зависимости

У проекта нет внешних зависимостей. 

Библиотека собирается с использованием MSYS2 и компилятора GCC.

# 3. Как собрать библиотеку
## 3.1. Использование CMake

### 3.1.1. Встраиваемая библиотека
Данная библиотека может использоваться в качестве _встраиваемой_ как папка в папке проекта :

В **главный** файл CMakeLists.txtl добавьте :
```cmake
# Если вы разместили библиотеку в папке lib: add_subdirectory(lib/colorconsole)
add_subdirectory(colorconsole) 
```

### 3.1.1. Статическая и разделяемая библиотеки

Данная библиотека может собираться с внешним проектом в качестве статической или разделяемой:

В **главный** файл CMakeLists.txtl добавьте :

```cmake
# ON - для сборки разделяемой, OFF - для сборки статической
option(BUILD_SHARED_LIBS "Build using shared libraries" OFF)
```


```cmake
target_link_libraries(${PROJECT_NAME} PRIVATE ccon::colorconsole)
```

## 3.2. Опции CMake

Библиотека предоставляет следующие опции **CMake**:
- BUILD_SHARED_LIBS = ON | OFF
    - ON - собирать как разделяемую библиотеку
    - OFF - собирать как статическую библиотеку

Использование:
- При конфигурировании проекта:
```shell
cmake -S . -B build -DBUILD_SHARED_LIBS=OFF
```


# 4. Как использовать библиотеку
## 4.1. Использование

_Примеры использования_

Пожалуйста обратитесь к документации класса `ccon::ColorConsole`.

## 4.2. Версии библиотеки
### 4.2.1. Совместимость

Проблем с совместимостью не обнаружено.


# 5. Документация

Все классы и функции были задокументированы с помощью Doxygen.


Чтобы собрать документацию, из папки docs запустите:

```shell
doxygen .\Doxyfile
```

# 6. Лицензия

Эта библиотека лицензирована под [лицензией GPLv3][repo-license-url].

<!-- Ссылки -->

[repo-license-url]: https://www.gnu.org/licenses/gpl-3.0.html

Запустим сборку документации:

cd c:\projects\colorconsolelib\docs
doxygen

Обратите внимание, запускать doxygen нужно именно из папки docs!

Откроем файл

docs\html\index.html

в любом браузере:

Обратите внимание ссылки на разделы главной страницы не работают на самой странице, но доступны в левой панели навигации.

Так как мы не добавили никакой документации в наш класс, то и у класса нет документации, только описание всех полей и методов.

Добавляем документацию Doxygen для класса С++

Установим в VSCode расширение:

Doxygen Documentation Generator

Автор:

Christoph Schlosser

Ссылка на расширение:

https://marketplace.visualstudio.com/items?itemName=cschlosser.doxdocgen

После установки откроем файл

src\colorconsole.cpp

Удалим старый блок комментариев в начале файла.

Добавим пустую строку и введем

/**

И нажмем Enter

С помощью установленного расширения будет добавлен блок комментариев:

/**
 * @file colorconsole.cpp
 * @author your name (you@domain.com)
 * @brief 
 * @version 0.1
 * @date 2025-09-02
 * 
 * @copyright Copyright (c) 2025
 * 
 */

Данное расширение для VSCode позволяет сильно экономить нам время при написании документации.

Так же я рекомендую установить:

Russian - Code Spell Checker

От автора:

Street Side Software

Для проверки орфографии комментариев, как его включить есть в описании, я рекомендую добавить в настройки пользователя:

"cSpell.language": "en,ru",

Я сразу приведу откомментированные файлы проекта:

src\colorconsole.h

/**
 * @file colorconsole.cpp
 * @author Василий Алтунин (skyr@altuninvv.ru)
 * @brief Файл содержит реализацию класса ColorConsole
 * @version 0.1.0
 * @date 2025-09-02
 *
 * @copyright Алтунин Василий 2025
 *
 */

#ifndef COLORCONSOLE_H
#define COLORCONSOLE_H

#include <windows.h>

class ColorConsole
{

public:

   
    /// @brief Черный   
    static const int BLACK = 0;

    /// @brief Темно-синий
    static const int DARK_BLUE = 1;

    /// @brief Темно-зеленый
    static const int DARK_GREEN = 2;

    /// @brief Темно-салатовый
    static const int DARK_CYAN = 3;

    /// @brief Темно-красный
    static const int DARK_RED = 4;

    /// @brief Темно-фиолетовый
    static const int DARK_MAGENTA = 5;

    /// @brief Темно-желтый
    static const int DARK_YELLOW = 6;

    /// @brief Светло-серый
    static const int LIGHT_GRAY = 7;

    /// @brief Темно-серый
    static const int DARK_GRAY = 8;

    /// @brief Светло-синий
    static const int LIGHT_BLUE = 9;

    /// @brief Светло-зеленый
    static const int LIGHT_GREEN = 10;

    /// @brief Светло-салатовый
    static const int LIGHT_CYAN = 11;

    /// @brief Светло-красный
    static const int LIGHT_RED = 12;

    /// @brief Светло-фиолетовый
    static const int LIGHT_MAGENTA = 13;

    /// @brief Светло-желтый
    static const int LIGHT_YELLOW = 14;

    /// @brief Белый
    static const int WHITE = 15;

    /**
     * @brief Конструктор класса ColorConsole
     *
     */
    ColorConsole();

    /**
     * @brief Деструктор класса ColorConsole
     *
     */
    ~ColorConsole();

    /**
     * @brief Инициализирует статические дескрипторы консоли
     * Обязательно должна быть вызвана перед использованием методов 
     * класса меняющих цвет текста в консоли!
     *  @param Returns Ничего не возвращает
     *
     */
    static void init();

    /**
     * @brief Дискриптор консоли stdout
     * 
     */
    static HANDLE __console_stdout_handle;
    /**
     * @brief Дискриптор консоли stderr
     * 
     */
    static HANDLE __console_stderr_handle;

    /**
     * @brief Устанавливает цвет текста и фона для консоли stdout
     *
     * @param color цвет текста
     * @param bgColor цвет фона
     * @param Returns Ничего не возвращает
     *   
     */
    static void setConsStdOutColor(int color, int bgColor = 0);

    /**
     * @brief Устанавливает цвет текста и фона для консоли stderr
     *
     * @param color цвет текста
     * @param bgColor цвет фона
     * @param Returns Ничего не возвращает
     *
     */
    static void setConsStdErrColor(int color, int bgColor = 0);

    /**
     * @brief Устанавливает цвет по умолчанию для консоли stdout (черный фон серый текст)
     * @param Returns
     *    Ничего не возвращает
     *
     */
    static void setConsStdOutDefColor();

    /**
     * @brief Устанавливает цвет по умолчанию для консоли stderr (черный фон серый текст)
     * @param Returns
     *    Ничего не возвращает
     *
     */
    static void setConsStdErrDefColor();

    /**
     * @brief Добавляет пустую линию с цветом по умолчанию (черный фон)
     * @param Returns
     *    Ничего не возвращает
     *
     */
    static void emptyLine();
};

#endif

Файл src\colorconsole.cpp:

/**
 * @file colorconsole.cpp
 * @author Василий Алтунин (skyr@altuninvv.ru)
 * @brief Файл содержит реализацию класса ColorConsole
 * @version 0.1.0
 * @date 02.09.2025
 *
 * @copyright Алтунин Василий 2025
 * 
 * Файл содержит реализацию класса ColorConsole позволяющего менять цвет текста и фона в консоли Windows.
 *
 */

#include "colorconsole.h"
#include <iostream>

/**
 * @brief Конструктор класса ColorConsole
 *
 */
ColorConsole::ColorConsole()
{
}

/**
 * @brief Деструктор класса ColorConsole
 *
 */
ColorConsole::~ColorConsole()
{
}

HANDLE ColorConsole::__console_stdout_handle;
HANDLE ColorConsole::__console_stderr_handle;

/**
 * @brief Инициализирует статические дескрипторы консоли
 * Обязательно должна быть вызвана перед использованием методов
 * класса меняющих цвет текста в консоли!
 *  @param Returns Ничего не возвращает
 *
 */
void ColorConsole::init()
{
    ColorConsole::__console_stdout_handle = GetStdHandle(STD_OUTPUT_HANDLE);
    ColorConsole::__console_stderr_handle = GetStdHandle(STD_ERROR_HANDLE);
}

/**
 * @brief Устанавливает цвет текста и фона для консоли stdout
 *
 * @param color цвет текста
 * @param bgColor цвет фона
 * @param Returns Ничего не возвращает
 *
 */
void ColorConsole::setConsStdOutColor(int color, int bgColor)
{
    SetConsoleTextAttribute(ColorConsole::__console_stdout_handle, color + (bgColor * 16));
}

/**
 * @brief Устанавливает цвет текста и фона для консоли stderr
 *
 * @param color цвет текста
 * @param bgColor цвет фона
 * @param Returns Ничего не возвращает
 *
 */
void ColorConsole::setConsStdErrColor(int color, int bgColor)
{
    SetConsoleTextAttribute(ColorConsole::__console_stderr_handle, color + (bgColor * 16));
}

/**
 * @brief Устанавливает цвет по умолчанию для консоли stdout (черный фон серый текст)
 * @param Returns Ничего не возвращает
 *
 */
void ColorConsole::setConsStdOutDefColor()
{
    SetConsoleTextAttribute(ColorConsole::__console_stdout_handle, 7);
}

/**
 * @brief Устанавливает цвет по умолчанию для консоли stderr (черный фон серый текст)
 * @param Returns Ничего не возвращает
 *
 */
void ColorConsole::setConsStdErrDefColor()
{
    SetConsoleTextAttribute(ColorConsole::__console_stderr_handle, 7);
}

/**
 * @brief Добавляет пустую линию с цветом по умолчанию (черный фон)
 * @param Returns Ничего не возвращает
 *
 */

void ColorConsole::emptyLine()
{
    ColorConsole::setConsStdErrDefColor();
    std::cout << std::endl;
}

Скопируем откоментированный заголовочный файл в папку Include:

cd c:\projects\colorconsolelib
copy /y src\colorconsole.h include\colorconsole\colorconsole.h

Запустим сборку:

cd c:\projects\colorconsolelib\docs
doxygen

Откроем файл с документацией:

c:\projects\colorconsolelib\docs\html\index.html

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

Заключение

Сегодня мы рассмотрели создание документации для библиотеки C++ с помощью Doxygen:

Установили Doxygen и требуемые библиотеки;

Создали папку для документации и файл конфигурации Doxygen;

Создали файл README.md для описания нашей библиотеки;

Установили расширения VSCode для работы с Doxygen и проверки орфографии в комментариях;

Задокументировали файлы с заголовком и реализацией класса с помощью Doxygen;

Собрали документацию с помощью Doxygen и проверили результат.

В следующей статье мы рассмотрим сборку документации с помощью CMake.

Категория C++

Теги Cpp Doxygen

Добавить комментарий