Поддерживает ли Swift генерацию документации? Есть ли встроенные средства?

Да, Swift поддерживает генерацию документации!

В Swift есть полноценная поддержка документирования кода, причём как встроенными средствами Xcode, так и отдельным инструментом DocC (Documentation Compiler), который появился начиная с Xcode 13. Вы можете создавать профессиональную HTML-документацию, аналогичную той, что вы видите на сайте Apple Developer.

1. Базовое документирование с помощью комментариев

Самый простой способ — использовать /// (три слеша) или многострочные комментарии /** ... */. Xcode автоматически распознаёт их и показывает в Quick Help (Alt+клик по символу).

Пример для вашего кода:

/// Класс для управления пользователями.
/// 
/// Используйте этот класс для получения и хранения данных пользователя.
class UserManager {
    /// Имя текущего пользователя.
    /// 
    /// По умолчанию пустая строка. Устанавливается после успешного входа.
    var userName: String = ""
    
    /// Загружает данные пользователя по его идентификатору.
    ///
    /// - Parameter userId: Уникальный идентификатор пользователя.
    /// - Returns: Строку с данными пользователя.
    /// - Warning: Этот метод выполняет синхронный запрос, не используйте в главном потоке.
    func fetchUserData(userId: Int) -> String {
        // тут какой-то код
        return "User data"
    }
}

Обратите внимание на теги - Parameter, - Returns, - Warning — это ключевые слова, которые DocC понимает. Полный список включает: Parameter, Returns, Throws, Precondition, Postcondition, Requires, Invariant, Complexity, Important, Warning, Note, Remark, SeeAlso, Author, Authors, Copyright, Date.

2. Генерация документации через DocC

DocC — это официальный инструмент Apple. Он позволяет создать статический сайт документации из ваших комментариев и дополнительных Markdown-файлов.

Как запустить:

• В Xcode: выберите меню Product → Build Documentation. Откроется окно документации.
• Для экспорта в HTML: используйте команду в терминале:

  xcrun docc convert Sources/YourModule.docc \
    --output-path ./docs \
    --hosting-base-path /your-site-path

• Также можно добавить схему сборки в Xcode: Product → Scheme → Edit Scheme → добавить действие "Build Documentation".

3. Расширенная документация с помощью .docc каталога

Для статей, руководств и обзоров создайте в проекте папку YourModule.docc и положите туда Markdown-файлы. Пример структуры:

MyApp/
├── Sources/
│   ├── MyApp/
│   │   ├── MyApp.docc/
│   │   │   ├── MyApp.md          # Главная страница
│   │   │   ├── GettingStarted.md # Статья
│   │   │   └── Tutorial.md       # Учебник
│   │   └── UserManager.swift
│   └── main.swift
└── Package.swift

Внутри Markdown можно ссылаться на символы кода обратными кавычками: ``UserManager``. DocC автоматически создаст гиперссылки.

4. Сторонние инструменты (если нужно что-то другое)

• Jazzy — популярный генератор документации, который создаёт HTML в стиле Apple. Устанавливается через Homebrew: brew install jazzy. Запуск: jazzy --min-acl internal.
• SourceDocs — лёгкий инструмент, который генерирует Markdown-файлы из комментариев.

Совет

Обязательно указывайте уровень доступа (public, open) для тех символов, которые должны попасть в документацию. DocC по умолчанию документирует только public и open. Чтобы включить internal, добавьте флаг --emit-digest или настройте схему.

Теперь вы можете писать чистый код с комментариями, а Xcode и DocC превратят их в красивую документацию!

# Установка через Homebrew
brew install jazzy

# Запуск в папке проекта
jazzy --min-acl internal --output docs