Разработка

Документируем код с помощью DocC

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

Опубликовано

3 дня назад

02.04.2025

Автор:

AppTractor

Сегодня я хотел бы поговорить о документировании Swift-кода с помощью DocC. Документирование вашего кода становится все более важным в эпоху модульных приложений. Всякий раз, когда различные части вашего приложения находятся в нескольких пакетах Swift, становится критически важным предоставить надлежащую документацию.

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

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

Лучшее время для написания комментариев — в начале процесса, когда вы пишете код. Написание комментариев в первую очередь делает документацию частью процесса проектирования. Это не только дает лучшую документацию, но и создает лучшие проекты

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

Синтаксис DocC довольно прост, но при этом эффективен. Вам не нужно создавать дополнительные файлы или использовать дополнительное программное обеспечение, DocC является частью компилятора Swift. Компилятор DocC получает документацию непосредственно из вашего исходного кода. Вместо того, чтобы ставить двойные косые черты для комментариев, используйте тройные косые черты для документации. Вот и все.

extension Array {
    /// Returns a random element based on the day of the month,
    /// which is calculated to determine the random index.
    func stableRandom(using date: Date = .now) throws -> Element {
        let day = Calendar.current.component(.day, from: date)
        
        if day < count {
            return self[day]
        } else {
            let index = day % count
            return self[index]
        }
    }
}

​x
 
extension Array {    /// Returns a random element based on the day of the month,    /// which is calculated to determine the random index.    func stableRandom(using date: Date = .now) throws -> Element {        let day = Calendar.current.component(.day, from: date)                if day < count {            return self[day]        } else {            let index = day % count            return self[index]        }    }}

Как вы можете видеть в примере выше, мы используем тройные слеши, чтобы добавить некоторую документацию к функции. Теперь вы можете использовать Option+Click в вашем редакторе Xcode, чтобы увидеть документацию функции. Это так просто.

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

extension Array {
    /// Returns a random element based on the day of the month,
    ///  which is calculated to determine the random index.
    ///
    /// The stableRandom function consistently returns the same element throughout
    /// the entire date. However, its value changes as soon as the date changes.
    func stableRandom(using date: Date = .now) throws -> Element {
        let day = Calendar.current.component(.day, from: date)
        
        if day < count {
            return self[day]
        } else {
            let index = day % count
            return self[index]
        }
    }
}

xxxxxxxxxx
 
extension Array {    /// Returns a random element based on the day of the month,    ///  which is calculated to determine the random index.    ///    /// The stableRandom function consistently returns the same element throughout    /// the entire date. However, its value changes as soon as the date changes.    func stableRandom(using date: Date = .now) throws -> Element {        let day = Calendar.current.component(.day, from: date)                if day < count {            return self[day]        } else {            let index = day % count            return self[index]        }    }}

Вы можете добавить информацию о параметрах, используя ключевое слово - Parameters:. Тире и двоеточие являются обязательными и используются в качестве индикаторов разделения. На новой строке имя параметра вы можете начать писать после еще одного тире с отступом; двоеточие после имени необходимо для разделения имени и его описания.

extension Array {
    /// Returns a random element based on the day of the month,
    ///  which is calculated to determine the random index.
    ///
    /// The stableRandom function consistently returns the same element throughout
    /// the entire date. However, its value changes as soon as the date changes.
    ///
    /// - Parameters:
    ///     - date: The date used in the randomization algorithm.
    func stableRandom(using date: Date = .now) throws -> Element {
        let day = Calendar.current.component(.day, from: date)
        
        if day < count {
            return self[day]
        } else {
            let index = day % count
            return self[index]
        }
    }
}

xxxxxxxxxx
 
extension Array {    /// Returns a random element based on the day of the month,    ///  which is calculated to determine the random index.    ///    /// The stableRandom function consistently returns the same element throughout    /// the entire date. However, its value changes as soon as the date changes.    ///    /// - Parameters:    ///     - date: The date used in the randomization algorithm.    func stableRandom(using date: Date = .now) throws -> Element {        let day = Calendar.current.component(.day, from: date)                if day < count {            return self[day]        } else {            let index = day % count            return self[index]        }    }}

Ключевые слова Returns и Throws позволяют нам указать описание для возвращаемых значений и выдачи ошибок. Синтаксис этих ключевых слов тот же: они начинаются с тире, заканчиваются двоеточием и затем содержат описание.

extension Array {
    /// Returns a random element based on the day of the month,
    ///  which is calculated to determine the random index.
    ///
    /// The stableRandom function consistently returns the same element throughout
    /// the entire date. However, its value changes as soon as the date changes.
    ///
    /// - Parameters:
    ///     - date: The date used in the randomization algorithm.
    ///
    /// - Returns: A random element of the array.
    ///
    /// - Throws: May throw an error whenever can't randomize the date
    func stableRandom(using date: Date = .now) throws -> Element {
        let day = Calendar.current.component(.day, from: date)
        
        if day < count {
            return self[day]
        } else {
            let index = day % count
            return self[index]
        }
    }
}

xxxxxxxxxx
 
extension Array {    /// Returns a random element based on the day of the month,    ///  which is calculated to determine the random index.    ///    /// The stableRandom function consistently returns the same element throughout    /// the entire date. However, its value changes as soon as the date changes.    ///    /// - Parameters:    ///     - date: The date used in the randomization algorithm.    ///    /// - Returns: A random element of the array.    ///    /// - Throws: May throw an error whenever can't randomize the date    func stableRandom(using date: Date = .now) throws -> Element {        let day = Calendar.current.component(.day, from: date)                if day < count {            return self[day]        } else {            let index = day % count            return self[index]        }    }}

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

extension Array {
    /// Returns a random element based on the day of the month,
    ///  which is calculated to determine the random index.
    ///
    /// The stableRandom function consistently returns the same element throughout
    /// the entire date. However, its value changes as soon as the date changes.
    ///
    /// - Parameters:
    ///     - date: The date used in the randomization algorithm.
    ///
    /// - Returns: A random element of the array.
    ///
    /// - Throws: May throw the ``RandomError.random`` error
    func stableRandom(using date: Date = .now) throws -> Element {
        let day = Calendar.current.component(.day, from: date)
        
        if day < count {
            return self[day]
        } else {
            let index = day % count
            return self[index]
        }
    }
}

xxxxxxxxxx
 
extension Array {    /// Returns a random element based on the day of the month,    ///  which is calculated to determine the random index.    ///    /// The stableRandom function consistently returns the same element throughout    /// the entire date. However, its value changes as soon as the date changes.    ///    /// - Parameters:    ///     - date: The date used in the randomization algorithm.    ///    /// - Returns: A random element of the array.    ///    /// - Throws: May throw the ``RandomError.random`` error    func stableRandom(using date: Date = .now) throws -> Element {        let day = Calendar.current.component(.day, from: date)                if day < count {            return self[day]        } else {            let index = day % count            return self[index]        }    }}

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

Даже если у вас хватит самодисциплины вернуться и написать комментарии (и не обманывайте себя: скорее всего, у вас ее нет), комментарии будут не очень хорошими. К этому моменту процесса вы уже мысленно завершили работу. В вашем сознании этот фрагмент кода готов; вы с нетерпением ждете следующего проекта.

Если вы нашли опечатку - выделите ее и нажмите Ctrl + Enter! Для связи с нами вы можете использовать info@apptractor.ru.