Документация PHP проекта: полное руководство по написанию

Онлайн-тренажер Python для начинающих

Изучайте Python легко и без перегрузки теорией. Решайте практические задачи с автоматической проверкой, получайте подсказки на русском языке и пишите код прямо в браузере — без необходимости что-либо устанавливать.

Начать курс

Введение: зачем нужна документация в PHP проектах?

Качественная документация — это не роскошь, а необходимость для любого PHP проекта, будь то небольшой фреймворк, библиотека или крупное веб-приложение. Хорошо написанная документация экономит часы разработки, упрощает онбординг новых участников команды и помогает избежать множества ошибок. Согласно опросу JetBrains, более 60% разработчиков считают недостаток документации одной из главных проблем при работе с чужим кодом.

В этой статье мы разберем, как правильно организовать процесс написания документации для PHP проекта: от базовых комментариев в коде до полноценной генерации технической документации. Вы узнаете о стандарте PHPDoc, лучших практиках форматирования и инструментах автоматизации.

Основы PHPDoc: документируем код правильно

PHPDoc — это стандарт аннотирования PHP кода, который позволяет описывать типы, параметры, возвращаемые значения и исключения. Он понимается большинством IDE (PhpStorm, VS Code) и инструментами генерации документации.

Структура DocBlock

Каждый DocBlock начинается с /** и заканчивается */. Внутри строки начинаются с *. Вот минимальный набор тегов:

@param — описание параметра функции/метода
@return — описание возвращаемого значения
@throws — исключения, которые может выбросить метод
@var — тип свойства класса
@see — ссылка на связанный элемент

<?php
/**
 * Рассчитывает финальную цену товара с учетом скидки.
 *
 * @param float $basePrice Базовая цена товара
 * @param float $discountPercent Процент скидки (от 0 до 100)
 * @return float Финальная цена после применения скидки
 * @throws InvalidArgumentException Если процент скидки выходит за пределы 0-100
 *
 * @see applyCoupon()
 */
function calculateFinalPrice(float $basePrice, float $discountPercent): float
{
    if ($discountPercent < 0 || $discountPercent > 100) {
        throw new InvalidArgumentException('Скидка должна быть от 0 до 100%');
    }
    return $basePrice * (1 - $discountPercent / 100);
}
?>

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

Для классов используйте теги @property (для магических свойств), @method (для магических методов) и @template (для обобщенных типов).

<?php
/**
 * Репозиторий для работы с пользователями.
 *
 * @template T of User
 * @method User|null findById(int $id) Найти пользователя по ID
 * @property-read int $count Количество пользователей
 */
class UserRepository
{
    /**
     * @var array<int, T> Хранилище пользователей
     */
    private array $users = [];

    /**
     * Добавляет пользователя в репозиторий.
     *
     * @param T $user Объект пользователя
     * @return int ID добавленного пользователя
     */
    public function add(User $user): int
    {
        // реализация
    }
}
?>

Автоматическая генерация документации: phpDocumentor и Doxygen

Ручное создание HTML-документации — трудоемкий процесс. К счастью, существуют инструменты, которые генерируют её автоматически из PHPDoc-комментариев.

phpDocumentor (phpDoc)

Самый популярный инструмент для PHP. Устанавливается через Composer:

composer require --dev phpdocumentor/phpdocumentor

Запуск генерации:

vendor/bin/phpdoc -d ./src -t ./docs

Где -d — директория с исходным кодом, -t — папка для готовой документации.

Настройка конфигурации

Создайте файл phpdoc.xml в корне проекта:

<?xml version="1.0" encoding="UTF-8"?>
<phpdocumentor>
    <title>Мой PHP проект</title>
    <paths>
        <output>docs/api</output>
        <source>src</source>
    </paths>
    <transformations>
        <template name="default"/>
    </transformations>
</phpdocumentor>

Doxygen + PHP

Doxygen поддерживает PHP и генерирует более детализированные диаграммы классов и графы вызовов. Для этого в конфигурации Doxyfile укажите:

INPUT = src
FILE_PATTERNS = *.php
OPTIMIZE_OUTPUT_FOR_C = NO
EXTRACT_ALL = YES

Документирование архитектуры: README, Wiki и ADR

Кодовая документация (DocBlock) — это только часть картины. Для полноценного проекта необходимы документы высокого уровня.

README.md: лицо проекта

В корне проекта обязательно должен быть файл README.md. Он должен содержать:

Краткое описание проекта (1-2 абзаца)
Требования (PHP версия, расширения)
Быстрый старт (установка, настройка)
Примеры использования с кодом
Ссылки на полную документацию и API

# MyPHP Library

Библиотека для работы с REST API сервиса Example.

## Требования
- PHP 8.1+
- ext-curl
- ext-json

## Установка
```bash
composer require myvendor/myphp-library
```

## Быстрый старт
```php
$client = new Client('api-key');
$users = $client->users()->getAll();
```