Написание документации для Swift проекта: от А до Я

Введение: Почему документация — это инвестиция в будущее вашего Swift проекта

Каждый разработчик iOS или macOS хотя бы раз сталкивался с ситуацией, когда чужой (или собственный) код через месяц превращается в «тёмный лес». Без качественной документации поддержка проекта становится кошмаром, а онбординг новых членов команды — неделями мучений. Для языка Swift, с его мощной системой типов и протоколами, документация особенно важна: она объясняет не только как работает код, но и почему он спроектирован именно так.

В этой статье мы разберём полный цикл написания документации для Swift проекта: от выбора инструментов до публикации. Вы узнаете, как использовать встроенные возможности Xcode, формат DocC и Markdown, чтобы ваша документация была понятной, актуальной и полезной.

1. Основы: Форматы и инструменты для Swift документации

1.1. Markdown и DocC — стандарт индустрии

Начиная с Xcode 13, Apple активно продвигает DocC (Documentation Compiler) — систему, которая объединяет комментарии в коде и Markdown-статьи в единый HTML-документ. DocC использует расширенный синтаксис Markdown, включая поддержку ссылок на символы, диаграммы и интерактивные примеры.

Базовый комментарий в Swift выглядит так:

/// Вычисляет факториал числа.
/// - Parameter number: Целое неотрицательное число.
/// - Returns: Факториал числа (UInt64).
/// - Warning: При number > 20 произойдёт переполнение.
func factorial(of number: UInt64) -> UInt64 {
    return (1...number).reduce(1, *)
}

1.2. Основные теги DocC

DocC поддерживает множество тегов для структурирования документации. Вот самые важные:

• /// - Parameter — описание параметра функции
• /// - Returns — описание возвращаемого значения
• /// - Throws — описание ошибок, которые может выбросить функция
• /// - Warning — важное предупреждение
• /// - Note — дополнительная заметка
• /// - Precondition — предусловия вызова
• /// - Complexity — оценка сложности алгоритма (O(n), O(log n) и т.д.)

Пример с несколькими тегами:

/// Загружает данные из сети.
/// - Parameter url: URL для запроса.
/// - Parameter timeout: Таймаут в секундах (по умолчанию 30).
/// - Throws: `NetworkError.invalidURL`, если url некорректен.
/// - Throws: `NetworkError.timeout`, если превышен таймаут.
/// - Returns: Данные типа `Data`.
/// - Complexity: O(1) для создания запроса.
func fetchData(from url: URL, timeout: TimeInterval = 30) async throws -> Data {
    // реализация
}

2. Структурирование документации: от модуля до метода

2.1. Документирование модулей и типов

Каждый публичный тип (класс, структура, перечисление) должен иметь краткое описание. Для модулей и крупных библиотек используйте отдельные Markdown-файлы в папке .docc вашего проекта.

/// Модуль для работы с пользовательскими настройками.
///
/// Этот модуль предоставляет типобезопасный интерфейс
/// для чтения и записи настроек в `UserDefaults`.
public struct SettingsManager {
    // ...
}

2.2. Документирование протоколов и расширений

Протоколы — одна из ключевых концепций Swift. Документируйте не только сам протокол, но и его требования:

/// Протокол для объектов, которые можно сериализовать в JSON.
public protocol JSONSerializable {
    /// Преобразует объект в словарь для JSON.
    /// - Returns: Словарь `[String: Any]`.
    func toDictionary() -> [String: Any]
}

extension JSONSerializable {
    /// Преобразует объект в JSON-строку.
    /// - Returns: Строка в формате JSON или nil при ошибке.
    func toJSONString() -> String? {
        guard let data = try? JSONSerialization.data(withJSONObject: toDictionary()) else { return nil }
        return String(data: data, encoding: .utf8)
    }
}

2.3. Примеры кода в документации

DocC позволяет вставлять выполняемые примеры кода прямо в описание. Это особенно полезно для фреймворков и SDK:

/// Создаёт кэш изображений с ограничением по памяти.
///
/// Пример использования:
///
/// ```swift
/// let cache = ImageCache(maxSizeMB: 100)
/// cache.store(UIImage(named: "photo")!, forKey: "photo")
/// let cachedImage = cache.retrieve(forKey: "photo")
/// ```
///
/// - Parameter maxSizeMB: Максимальный размер кэша в мегабайтах.
public class ImageCache {
    // ...
}

3. Генерация и публикация документации

3.1. Сборка документации в Xcode

Самый простой способ сгенерировать документацию — использовать встроенные возможности Xcode:

1. Выберите target вашего проекта
2. Меню Product → Build Documentation
3. Готовая документация откроется в окне Developer Documentation

Для более тонкой настройки создайте файл YourProject.docc/Documentation.md — это будет главная страница вашей документации.

3.2. Экспорт в статический сайт

DocC умеет генерировать статический HTML, который можно разместить на любом хостинге или GitHub Pages:

# В терминале, из папки проекта
xcodebuild docbuild -scheme YourScheme -destination 'generic/platform=iOS' -derivedDataPath ./Build

# Найти архив документации в папке Build/Build/Products/Debug-iphoneos/
# и преобразовать его в статический сайт
xcrun docc process-archive transform-for-static-hosting \
  Build/Build/Products/Debug-iphoneos/YourScheme.doccarchive \
  --output-path ./docs

После этого папка docs будет содержать готовый сайт. Вы можете загрузить его на GitHub Pages или любой веб-сервер.

3.3. Автоматизация через CI/CD

Добавьте генерацию документации в ваш пайплайн (например, GitHub Actions):

# .github/workflows/docs.yml
name: Generate Documentation
on:
  push:
    branches: [main]
jobs:
  build-docs:
    runs-on: macos-latest
    steps:
      -