Документация swift: Архивы Документация — SwiftBook

Содержание

Разработка iOS на Swift в примерах на русском

Сайт, который Вы сейчас открыли, был создан с целью собрать знания по теме программирование в среде iOS. Программирование под iOS будет осуществляться в среде разработки Xcode, на языке программирования Swift, который Apple представила широкой общественности в 2014 г. Для начала я буду складывать на сайте все полезности с примерами. Но если у блога появятся постоянная аудитория, то статьи  на сайте будут появляться, согласно мнения общественности.

Итак, для кого же этот сайт? Сайт рассчитан на пользователей, которые немного понимают синтаксис Swift, делали первые попытки Swift программирования или пытались найти ресурсы, где бы присутствовала  документация Swift на русском. Однако на сайте также присутствует раздел для программистов, которые хотят изучить  программирование на swift с нуля. В этом разделе собраны ссылки и материалы, которые по мнению редакции, помогут освоить тонкости разработки iOS приложений.

Хотелось бы обратить внимание на несколько моментов…

Если вы разрабатываете приложения iOS или ищите документацию Apple Swift, то хорошо понимаете, что основная масса информации на английском языке. Исторически сложилось, что для изучения документации нужно знать английский. Наша редакция очень сильно постарается размещать материалы, документацию Swift на русском. Однако если будет интересный материал, но не будет альтернативы на русском языке, то ссылка на этот материал все же будет размещена, но будет отдельно помечена.

Статьи в блоге условно можно разделить на две части: теория и фундаментальные основы iOS Swift, и реальные примеры, которые проверены в системе разработки Xcode. Для отбора статей с примерами можно выбрать рубрику, которая так  и называется «Реальные примеры«

Критику и предложения можно оставлять в комментариях. Наша редакция всегда готова поучится чему-то новому и открыта для сотрудничества.

С уважением, команда proSwift.

ru

31 ссылка для тех, кто хочет освоить iOS-разработку — Академия Яндекса

Развитие языка Swift снизило и так невысокий порог вхождения в iOS-разработку. Изучать сам язык, среду разработки и практики написания кода на нём — одно удовольствие. Но это не значит, что писать для платформ Apple просто или непрестижно: iOS-разработчики востребованы в большинстве крупных компаний. Ссылки на статьи и другие материалы в этом списке подобрал Артур Антонов — разработчик в команде приложения Яндекс.Переводчик.

Советы будут полезны будущим стажёрам Яндекса, а также всем остальным, кто хочет создавать приложения в режиме полного цикла, знать инструменты и основные фреймворки, придумывать архитектуру сервисов, писать производительный код без багов и угадывать мысли цензоров App Store. Если вы уже уверены в своих силах и готовы применять знания на практике, то вы можете податься на летнюю стажировку для iOS-разработчиков.

Инструменты платформы

Если вы только начинаете знакомиться с SDK, набором библиотек для iOS или хотите систематизировать знания в области создания приложений — пройдитесь по этим ссылкам.

Документация Apple, конечно же

Когда в марте 2008 года Apple представила первый SDK (тогда ещё для iPhone OS), больше ста тысяч человек загрузили его за первые две недели после релиза. Но тогда мало кто подозревал, какой бум iOS ждёт нас впереди. Сейчас Apple предлагает очень много полезной информации: ссылки на API, статьи, код. Лучше сначала ознакомиться с содержанием, а потом возвращаться в документацию по необходимости. 

Статьи про отдельные библиотеки iOS

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

Рассылка про iOS-разработку

Если вы мобильный разработчик или только собираетесь им стать, то вы наверняка уже слышали рекомендации подписаться на ряд email-рассылок. Вот всего одна, зато исчерпывающая и с очень чёткой структурой. Её ведёт независимый iOS-разработчик Дэйв Вервер. Внутри — новости индустрии за неделю, ссылки на полезные тулзы, GitHub и многое другое.

На кого стоит подписаться в твиттере

Твиттер — источник остросоциальных тем, новых мемов и идей для iOS-разработки. По ссылке вы найдёте список из 52 сильнейших специалистов индустрии: подписывайтесь, чтобы первыми узнавать важные новости, участвовать в обсуждениях и просто быть в теме.

Интерфейс

Фреймворк UIKit позволяет строить интерфейсы iOS-приложений и обрабатывать действия пользователя. В прошлом году Apple представила SwiftUI, который однажды должен заменить UIKit — но переходный период будет долгим, и ещё в течение нескольких лет большинству разработчиков потребуется знать оба фреймворка.

Документация по UIKit

Официальная документация от Apple очень подробная и становится со временем всё лучше: её точно будет полезно изучить новичкам, но даже при наличии опыта получится найти что-то интересное. Она покрывает большинство тем — от структуры приложения и методов пользовательского ввода до защиты данных и взаимодействия с самой iOS. Обратите внимание на раздел про UIView и его наследников.

Видеокурс по созданию приложения с UIKit

Если вам пока сложно разобраться с UIKit самостоятельно, обратите внимание на этот англоязычный видеокурс. Он создан для абсолютных новичков: опыт в создании iOS-приложений или знание Swift не понадобятся. Первые уроки в игровой форме рассказывают про основные понятия и термины. Все видео короткие — самые длинные идут около 9 минут — и бесплатные.

Туториалы по созданию интерфейса

Статьи про UI в. iOS-приложениях. Тут и про добавление разных элементов (например, контекстного меню или навигации), и про начало работы с анимацией, и про SnapKit для iOS. Основная ценность статей заключается в том, что это полноценные инструкции: со всеми подробностями и комментариями для новичков. Тексты, конечно, тоже на английском языке.

Туториалы по SwiftUI

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

Архитектура

Самый ответственный этап в создании приложения — выбор архитектуры и принципов, по которым вы планируете вести разработку. Чем позже вы найдёте ошибку, допущенную при проектировании, тем сложнее будет её исправить. Изучите материалы по этим ссылкам, чтобы сразу выбрать правильную концепцию приложения.

Примеры SOLID

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

GoF-паттерны с примерами

На этом сайте собрана исчерпывающая информация о паттернах проектирования. Автор предлагает начать с основ: изучить историю создания, задуматься о пользе, почитать критику и узнать всё о классификации. Самое ценное здесь — это сам каталог паттернов.

Clean Architecture

Статья на Хабре, которая призвана донести до сообщества детали концепции Clean Architecture и популярные заблуждения, связанные с ней.

Обзор архитектурных паттернов в iOS

iOS-разработчик из Badoo сравнивает популярные архитектурные практики и рассказывает о своих выводах. Всего автор разбирает четыре архитектурных паттерна: MVC, MVP, MVVM и VIPER. Впечатления от каждого из них в формате «ожидание/реальность» от практикующего разработчика — полезное чтение для новичков в этой теме.

Список опенсорсных iOS-приложений

Действительно огромный список опенсорсных приложений для iOS, watchOS и tvOS. Они распределены по категориям, и к каждому приложению есть небольшое описание Посмотрите, как устроены приложения, или примите участие в развитии любого из проектов на GitHub.

Многопоточность

Концепция многопоточного программирования отлично укладывается в общую идеологию iOS. Запускать процессы в отдельных потоках можно с помощью понятного набора инструментов, который только улучшился с развитием языка Swift. Эта часть списка посвящена Grand Central Dispatch — технологии Apple для управления параллельными операциями. Можно почитать и о некоторых других опциях — знания в области многопоточности пригодятся и на собеседовании, и в продакшене.

Введение в многопоточность iOS

Туториал по улучшению отзывчивости приложений при помощи GCD. Это первая часть большого учебника, которая поможет разобраться, как использовать GCD, а также познакомит с основными функциями, плюсами и минусами API. В рамках туториала авторы предлагают не просто почитать теорию, но и попробовать применить её на практике. Для этого вместе с учебными материалами вы получите почти готовый проект под названием GooglyPuff. Сможете оптимизировать его с помощью GCD — и миссия выполнена!

Архивный гайд от Apple

Несмотря на то, что это руководство за 2012 год, мы советуем не обходить его стороной. Возможно, будет полезно даже начать с него, если вы впервые знакомитесь с темой многопоточности. Внутри вас ждёт подробное описание главных процессов: вы познакомитесь с основами асинхронного проектирования приложений, узнаете про выполнение задач с помощью объектов Objective-C и асинхронную обработку системных событий. Бонус — словарь с основными терминами.

objc.io про многопоточность

objc.io — проект трёх разработчиков из Берлина: Криса Эйдхофома, Даниэля Эггерта и Флориана Куглера. В далёком 2013 году они создали этот сайт, чтобы обсуждать темы, актуальные для всех разработчиков iOS и macOS. Прошло много времени, ребята выпустили целых пять книг и написали множество материалов — самостоятельно и с крутыми экспертами. По ссылке — выпуск на тему многопоточности. Вместе с автором библиотеки PSPDFKit Питером Штейнбергером и опытным разаботчиком Тобиасом Кранцером они рассказывают об основных методах, проблемах и подводных камнях параллельного программирования.

Отладка

Отладка здесь — это не только поиск багов. Инструментарий iOS-разработчика позволяет вам делать структуру кода более прозрачной и видеть больше свойств приложения прямо во время программирования.

Cессия WWDC

Видео доклада с WWDC 2018 — это целый час ценнейшей информации про методы отладки Xcode. Вы узнаете, как использовать популярный дебаггер LLDB и брейкпоинты для исправления ошибок в вашем приложении и что нужно сделать, чтобы получить максимум от инструментов отладки Xcode. Всё это с примерами и подробными объяснениями.

Выпуск objc.io про отладку

Целый урок про отладку приложений от objc.io. Начинается он с разбора кейса — автор рассказывает о процессе и инструментах, которые он использовал для отслеживания ошибки регрессии в UIKit. После этого полезного чтения вас ждут не менее интересные размышления про LLDB и технологии DTrace и Activity Tracing.

Отладка приложений под iOS

Роман Ермолов руководит группой разработки приложения Яндекс для iOS. В этом докладе от 2015 года он говорит про интересные возможности LLDB, отладку иерархии UIView и отладку без исходников. Бонус — реальные примеры и дискуссия по теме в конце доклада.

Как работает LLDB

Во всех вышеперечисленных источниках много внимания уделяется именно этому отладчику. Хотите разобраться во всех нюансах его работы? Тогда вам точно пригодится этот доклад с WWDC 2019. Вы узнаете про разные способы отображения значений, форматирование пользовательских типов данных и (самое интересное!) расширение LLDB с помощью собственных сценариев Python 3.

Устройство Objective-C Runtime

Майк Эш — программист и пилот планера, который живет в Вашингтоне. Впечатляет? Это вы ещё не видели его блог! В нём он делится полезным софтом, делает остроумные посты в формате Q&A по пятницам и рассказывает о полётах. В этом старом (2009 год), но всё ещё полезном материале он рассуждает об Objective-C Runtime. Максимально подробное объяснение поможет разобраться в теме даже новичкам.

Оптимизация

Недостаточно просто придумать приложение, написать код и опубликовать результат в App Store. Нужно, чтобы оно хорошо работало: запуск не занимал много времени, реакция на ввод данных была мгновенной, а батарея не разряжалась из-за большого количества сетевых запросов.

Обзорная статья Apple

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

Вводная сессия WWDC об инструментах

Если вы хотите больше узнать про инструментарий Xcode, посмотрите видео с WWDC-2019. Это получасовой рассказ с примерами, который поможет разобраться с такими вещами, как шаблоны для профилирования производительности приложений и поиск «узких» мест в коде. Все описанные спикером инструменты призваны существенно повысить скорость отклика вашего приложения.

Сессия WWDC о подходах к оптимизации

Ещё одно видео с конференции Apple, но уже за 2018 год. Оно позволит глобально взглянуть на тему оптимизации: спикеры говорят об общем подходе и стратегиях, которых стоит придерживаться. Однако тут тоже не обошлось без практических советов, основанных на опыте авторов: они приложили руку к нескольким популярным приложениям от самой Apple. В видео рассказывается о том, как научиться пользоваться пакетом Instruments и другими возможностями Xcode.

Книга о внутреннем устройстве iOS и macOS

Продолжаем погружаться в тему — нужно ещё больше теории. По ссылке вы найдёте почти 800 страниц авторства Джонатана Левина с информацией практически обо всём, что когда-либо интересовало вас в работе с iOS. Чтобы разобраться в принципах работы системы, автор активно пользуется реверс-инжинирингом (обратной разработкой) и учит читателей делать то же самое. Вас ждёт большое количеством практических примеров, иллюстраций, скриншотов и ссылок на открытый исходный код от Apple.

Доклад об оптимизации запуска приложения

Вернёмся к практике. В этом видео руководитель службы мобильной разработки Яндекс. Карт Николай Лихогруд рассказывает об оптимизации времени запуска iOS-приложения Карт. На примере реального кейса вы узнаете, как правильно измерять время запуска, оптимизировать системную и пользовательскую части и поддерживать результат в следующих версиях.

Публикация в App Store

Многие разработчики, включая сотрудников Яндекса, недооценивали сложность процесса подписи iOS-приложения и модерации в App Store. Казалось бы, у вас всё готово: программа работает, вы хотите начать распространять её среди клиентов. Но у Apple есть правила, которым ваш код должен соответствовать.

Как загрузить приложение в App Store

Начните с пошаговой инструкции. Она выгодно отличается от публикаций на других ресурсах своей актуальностью: это популярный гайд от разработчиков Густаво Амброзио и Тони Дабура, обновлённый в 2020 году — с информацией из последней версии Xcode.

Подробный разбор подписи приложения

Ещё одна классная статья на сайте objc.io. Автор считает, что механизм подписи и подготовки кода — одна из самых сложных вещей, с которыми сталкивается iOS-разработчик. Поэтому он подробно описывает процесс: почитайте, чтобы понимать, что и зачем вы делаете. Но учитывайте, что статья написана в далёком 2014 году.

Обзор инструментов Xcode для подписи приложения

Для тех, кто хочет совсем углубиться в тему и разобраться: презентация Apple про функции Xcode, которые упрощают процессы управления сертификатами, подпись приложений и настройку параметров сборки проекта. Это видео с конференции WWDC 2016. Именно тогда компания представила обновлённый способ управления конфигурацией подписи с включенным по умолчанию автоматическим режимом.

Непрерывная интеграция

Пара дополнительных ссылок для тех, кто уже программирует под iOS и теперь беспокоится, как соотнести и объединить свой труд с результатами коллег по команде.

Подать заявку на стажировку для iOS-разработчиков

: РОССИЙСКАЯ НАЦИОНАЛЬНАЯ АССОЦИАЦИЯ SWIFT :: ДОКУМЕНТАЦИЯ

Российской Национальной Ассоциацией SWIFT подготовлен перевод на русский язык Руководства пользователя SWIFT (UHB) версии ноября 2020 года, в который вошли следующие тома:

Корпоративные и правовые документы:

Словарь терминов
Устав SWIFT
Правила корпорации
Общие положения и условия
Прайс-лист на Сообщения и Решения SWIFT
Процедура оформления заказа, выставление счетов и порядок оплаты
Код BIC: Общие правила (Политика BIC)
Правила защиты персональных данных

 Описание сервисов:

MA–CUG. Для корпораций
SCORE 2.6. Для корпораций

Расследования и обработка нестандартных ситуаций

(Exceptions and Investigations) E&I версия 1.2

Описание
Банк-Банк. Руководство по использованию сообщений
Руководство по интеграции

Bulk Payments 2.1
Cash reporting 5.0

SWIFTNet FIN:

Коды ошибок FIN
Описание службы FIN
Системные сообщения FIN
Стандарты МТ. Рекомендации по использованию
Стандарты. Общая информация

Стандарты:

Категория 1 – Клиентские платежи и чеки
Категория 2 – Переводы финансовых организаций
Категория 3
– Рынки финансовых ресурсов – валютообменные и денежные операции, производные инструменты. Том 1 (МТ 300 – МТ 341)
– Рынки финансовых ресурсов – валютообменные и денежные операции, производные инструменты. Том 2 (МТ 350 – МТ 399)

Категория 4 – Инкассо и кассовые письма
Категория 5
– Рынки ценных бумаг. Рекомендации по использованию сообщений
Рынки ценных бумаг. Том 1 (МТ 500 – 518)
Рынки ценных бумаг. Том 2 (МТ 519 – 543)
Рынки ценных бумаг. Том 3 (МТ 544 – 567)
Рынки ценных бумаг. Том 4 (МТ 568 – 599)

Категория 6 – Рынки финансовых ресурсов - Товары
Категория 7 – Документарные аккредитивы и гарантии
Категория 8 – Дорожные чеки
Категория 9 – Управление денежными средствами и статус клиента
Категория n – Сообщения общей группы

Рекомендации:

SWIFT-RUR

SWIFT-RUR (на английском языке)

SWIFT-RUS

SWIFT-RUS (на английском языке)

ISO 20022.RU

Актуальные версии томов выкладываются в разделе Документация Ресурс-центра РОССВИФТ* по мере их изготовления.


* Для доступа к Ресурс-центру требуется авторизация на сайте РОССВИФТ. Заполнение авторизационной формы будет предложено Вам автоматически. Вам потребуется ввести Ваши логин и пароль. Если Вы еще не зарегистрированы, то в авторизационной форме нажмите на ссылку Регистрация и заполните регистрационную форму. После валидации Ваших данных модератором, Вам будут высланы логин и пароль.

 

 

Как использовать Swift комментарии к документации



У меня есть несколько вопросов о комментариях к документации Swift:

  1. Есть ли способ сделать раздел связанных деклараций таким же, как в некоторых документах Apple? Например, когда я Option + Click метод tablewView(_:heightForRowAtIndexPath:) , он связывает меня с тремя другими связанными методами в сгенерированной документации.

  2. Есть ли какой-нибудь предупреждающий тег в Swift? Я знаю, что Objective-C позволил мне сделать @warning и получить жирное предупреждение в сгенерированной документации. Однако :warning: ничего не делает в комментариях к документации Swift, поэтому мне было любопытно, есть ли другой способ.

  3. Есть ли способ превратить мою документацию в файл HTML, который имеет такой же формат, как документация Apple? Я знаю, что в других IDEs, таких как Eclipse, я могу создать документацию HTML для своего кода. У XCode есть это?

ios xcode swift xcode6 documentation-generation
Поделиться Источник ad121     31 декабря 2014 в 03:57

5 ответов




113

Этот ответ был в последний раз пересмотрен для Swift 5.2 и Xcode 11.4.


Вы можете использовать markup для написания стандартной документации по коду (используя /// или /** */ ) и богатой документации по игровой площадке (используя //: или /*: */ ).

/// This function returns a welcoming string for a given `subject`.
///
/// ```
/// print(hello("World")) // Hello, World!
/// ```
///
/// - Warning: The returned string is not localized.
/// - Parameter subject: The subject to be welcomed.
/// - Returns: A hello string to the `subject`.
func hello(_ subject: String) -> String {
    return "Hello, \(subject)!"
}

Что касается документирования связанных символов, существует тег SeeAlso markup, но требуется, чтобы вы написали явный URL на странице документации по связанному символу.

Если вы хотите создать индекс документации HTML для своего проекта, я рекомендую проверить jazzy и swift-doc . Оба они являются потрясающими проектами с открытым исходным кодом и даже используются самой Apple.

Поделиться akashivskyy     04 января 2015 в 14:07



48

Xcode 7.0 бета 4

Нотация была изменена ( :param: больше не работает ...)

/// Creates the string representation of the poo with requested size.
///
/// - warning: Be carefull! Poos can hurt.
/// - parameter size: requested size of the poo
/// - returns: string representation of the poo
func makePoo(size: String) -> String
{
    return "Ouch. This is \(size) poo!"
}

И это выглядит так:

Вы можете использовать либо /// , либо /** */

Поделиться stevo.mit     27 июля 2015 в 08:05



24

Для тех, кто хочет добавить это как фрагмент кода. Swift 5, XCode 11.3+

Это дополнение к ответу йогендры Сингха в этой теме

/**
<#Summay text for documentation#>

- parameter <#parameterName#>: <#Description#>.
- returns: <#Return values#>
- warning: <#Warning if any#>


 # Notes: #
 1. <#Notes if any#>

 # Example #
```
 // <#Example code if any#>
```

*/

Скопируйте и вставьте приведенный выше код в Xcode. Выберите код и щелкните правой кнопкой мыши.

Сохраните фрагмент кода и укажите имя завершения в качестве документации.

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

Поделиться abhimuralidharan     21 января 2020 в 10:01


  • Есть ли у Swift поддержка генерации документации?

    Многие языки поддерживают комментарии к документации , позволяющие генератору (например, javadoc или doxygen ) генерировать документацию по коду путем анализа того же кода. Есть ли у Swift какая-либо функция комментария документации типа, подобная этой?

  • Swift комментарий к стандартной документации

    Существует ли стандартный способ написания комментария к документации на языке Swift? Что-то эквивалентное javadoc (Java) или docstrings (Python)? пример: /** * My docstring example * @return the String foo */ func foo() -> String { return Foo }



7

Используйте следующие обозначения для комментариев к документации.

/**
 This method sum two double numbers and returns.

 Here is the discussion. This methods adds two double and return the optional Double.


 - parameter number1: First Double Number.
 - parameter number2: Second Double Number.
 - returns: The sum of two double numbers.

 # Notes: #
 1. Parameters must be **double** type
 2. Handle return type because it is optional.

 # Example #
```
 if let sum = self.add(number1: 23, number2: 34) {
  print(sum)
 }
 ```
*/


func add(number1: Double, number2: Double) -> Double? {
    return number1 + number2
}

Поделиться Yogendra Singh     29 марта 2019 в 11:20



5

(3) Для создания документации в HTML (или даже для создания наборов документов) я настоятельно рекомендую jazzy , который был создан для этой цели.

Даже если это все еще WIP, он работает очень хорошо и генерирует документацию с аналогичной презентацией документации Apple

Поделиться AliSoftware     08 февраля 2015 в 22:20


Похожие вопросы:


Как добавить элементы, заключенные в<>, в комментарии к документации

Я пытаюсь писать комментарии к документации, но у меня есть проблема. /// <summary> /// Inserts an element into the System.Collections.Generic.List<T> at the specified /// index. ///...


XML комментарии к документации с интерфейсами и реализующими классами)

Я документирую assembly, используя комментарии к документации XML , из которых будет создан файл chm с помощью Sandcastle . My assembly содержит различные интерфейсы, каждый из которых реализован...


как использовать мои комментарии к документации в моих проектах, таких как документация android?

Я создаю комментарии к документации для исходного кода моего проекта в виде библиотеки. и как использовать их, как документацию android в новом проекте, использующем эту библиотеку?


Комментарии к документации в C#: каковы технические причины предпочесть /// или /**

В приложении а к спецификации языка C# рассматриваются комментарии к документации, и в нем говорится, что существует две формы: single-line-doc-comment: /// ввода-charactersopt...


Как читать комментарии к документации XML с помощью Roslyn

Я хотел бы иметь возможность читать комментарии к документации XML при разборе исходного кода C# с помощью Roslyn. /// <summary> /// Documentation... /// </summary> Я попытался...


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

Многие языки поддерживают комментарии к документации , позволяющие генератору (например, javadoc или doxygen ) генерировать документацию по коду путем анализа того же кода. Есть ли у Swift...


Swift комментарий к стандартной документации

Существует ли стандартный способ написания комментария к документации на языке Swift? Что-то эквивалентное javadoc (Java) или docstrings (Python)? пример: /** * My docstring example * @return the...


Swift комментарии к документации для переопределенных методов?

Я хотел бы добавить документацию markup к функции Swift, которая реализуется благодаря тому, что класс соответствует UICollectionViewDataSource . Например: /// /// - returns: Why is this...


Xcode 7 - Swift TODO комментарии

Используя Xcode 7 и Swift 2.0, я пытаюсь использовать TODO комментария, как в Visual Studio с C#. я нашел сайты, предлагающие // MARK: comment here // TODO: comment here // FIXME: comment here но ни...


Есть ли какой-нибудь способ сложить/свернуть комментарии к документации Rust в Visual Studio Code?

В VSCode есть ли способ сложить / свернуть комментарии документации Rust (т. е. комментарии новой строки, которые начинаются с: //! и /// )? Swift имеет аналогичные комментарии, поэтому любые...

Swift документация, вводная | Каморка сурового программиста

Данная статья изначально задумывалась как выборка самых интересных и неявных моментов выявленных во время прочтения официальной книги по Swift от Apple – “The Swift Programming Language“, но в процессе написания все больше приходило понимание, что будет крайне тяжело решить что оставить, а что выкинуть из описания языка. С другой стороны некоторые моменты хотелось дать более развернуто, некоторые исходные коды сделать пусть более академическим, зато более сжатыми, чтобы при необходимости окинуть взглядом небольшой кусочек кода и пробежавшись по сноскам понять максимальное количество подводных камней. А когда я взялся за вторую книгу от Apple – “Using Swift with Cocoa and Objective-C“, то понял что часть информации дублируется, и проще будет слить все воедино.
Таким образом перед вами сжатое изложение на русском языке двух основополагающих книг от Apple по swift. Развернуто я постарался рассмотреть optionals и строки, проведя свои исследования как это устроено или как проще с ними работать.
Так же хочу отметить проблему с терминологией, я не профессиональный переводчик, и к некоторым словам было тяжело подобрать перевод, так что в конце статьи будет словарик, в котором я приведу мои переводы некоторых слов и словосочетаний. При этом я постараюсь использовать и оригинальные английские варианты, чтобы проще было искать по поиску.
Весь код первой книги проверялся на Swift 1.2, но ближе к концу написания – я поставил бету XCode 7 и увидел, что в Swift 2.0 println – убрали, теперь есть только print, так что я тоже решил использовать print, все равно все там будем рано или поздно. Ну и заодно прогнал весь код на XCode Beta 7, проверив на валидность.
Итак, начнем.

GitHub - hhru/kotlin-swift-interopedia

Common
Internal modifier Internal-функции и классы не видны в Swift Так и есть, с iOS-разработчиками придётся обсуждать только публичное API общего кода
JavaDoc comments Комментарии видны в XCode ⚠️ Комментарии видны, если добавить специальный аргумент для компилятора
Data types
Primitive types Типы, объявленные в Kotlin, можно без изменений использовать в Swift ⚠️ Может требоваться маппинг для целочисленных типов данных / маппинги для Char-а
Optional (nullable) primitive types Тип, объявленный как Nullable, является таковым и на стороне Swift / Пользоваться nullable-типами можно без изменений ⚠️ Для примитивных типов требуется маппинг в специальные optional-типы / особенности с Char?
Mutable, immutable collections Сигнатуры List / MutableList / etc имеют значение в Swift-мире и тоже регулируют мутабельность ; Использование коллекций не отличается от Kotlin ⚠️ Для регулировки мутабельности используются ключевые слова let, var / Для мутабельных коллекций требуются дополнительные маппинги
Collections with primitive types Коллекции с элементами примитивных типов не требуют дополнительных маппингов ⚠️ Маппинги не требуются только для String-типа
Collections with custom types data Коллекции с элементами кастомных типов не требуют дополнительных маппингов Маппинги не требуются 👍
Unit and Nothing Типы Unit и Nothing можно использовать так же, как в Kotlin: Unit как объект или void, Nothing - нельзя создать Реальность соответствует ожиданиям 👍
Usual workflow
Top-level functions Функцию можно использовать напрямую после импорта, аналогично Kotlin-у ⚠️ Появляется класс-обёртка: UtilityKt.topLevelFunction()
Top-level val properties (readonly) Доступ к свойству можно получить напрямую после импорта, аналогично Kotlin-у / поле readonly ⚠️ Появляется класс-обёртка для доступа к свойству: UtilityKt.propertyVal
Top-level var properties (mutable) Доступ к свойству можно получить напрямую после импорта, аналогично Kotlin-у / поле mutable ⚠️ Появляется класс-обёртка для доступа к свойству: UtilityKt.propertyVar
Extension function over platform class Функцию можно использовать на объекте платформенного класса ⚠️ Появляется класс-обёртка с методом, принимающим объект нужного класса
Extension properties over platform class Доступ к свойству можно получить с помощью объекта платформенного класса ⚠️ Появляется класс-обёртка с методом, принимающим объект нужного класса
Extension properties for companion object of platform class Доступ к свойству можно получить с помощью платформенного класса 🚫 В .h-файле свойство есть, а в Swift-е не получается использовать
Extension functions over usual class Функцию можно использовать на объекте класса Реальность соответствует ожиданиям 👍
Extension properties over usual class Доступ к свойству можно получить через объект класса Реальность соответствует ожиданиям 👍
Extension properties for companion object of usual class Доступ к свойству можно получить через класс ⚠️ Доступ к свойству можно получить через объект companion
Usual class constructor Работа с конструктором не отличается от Kotlin-а Реальность соответствует ожиданиям 👍
Usual class val property (readonly) Доступ к свойству есть из объекта класса / свойство readonly Реальность соответствует ожиданиям 👍
Usual class var property (mutable) Доступ к свойству есть из объекта класса / свойство mutable Реальность соответствует ожиданиям 👍
Usual class functions Работа с функциями, объявленными внутри класса, не отличается от Kotlin-а Реальность соответствует ожиданиям 👍
Companion object Доступ к свойствам и функциям, объявленным в companion object-е, аналогичен Kotlin-у ⚠️ Доступ есть через вспомогательный объект companion
Objects Доступ к свойствам и функциям, объявленным в object-е, аналогичен Kotlin-у ⚠️ Доступ есть через вспомогательный объект shared
Function with default arguments Работа с функциями, имеющими дефолтные аргументы, аналогична Kotlin-у 🚫 Всегда приходится указывать все аргументы функции
Constructor with default arguments Работа с конструктором, имеющим дефолтные аргументы, аналогична Kotlin-у 🚫 Всегда приходится указывать все аргументы для конструктора
Classes
Abstract class Можно отнаследоваться от абстрактного класса, IDE подсказывает какие методы надо переопределить ⚠️ В IDE нет подсказок о необходимости переопределить абстрактный метод
Annotation class Аннотации можно использовать в Swift 🚫 Аннотации не попали в .h-файл
Data class Data class-ы сохраняют свои свойства после перехода в Swift ⚠️ Не все возможности data class-ов сохраняются / есть особенности с copy
Enum class Kotlin-овский enum class превратится в enum Swift-а, и можно будет использовать switch ⚠️ Не работает как ожидается. Но сгенерировался объект со статическими элементами
Inner class Можно создать инстанс inner-класса / прямого доступа к родительским свойствам и функциям нет ⚠️ Небольшие отличия в синтаксисе создания
Open class Можно наследоваться от open-класса / есть доступ к protected-полям / можно переопределять open-методы Можно переопределять и final-методы
Sealed class Корректно конвертируется в структуру, которую можно передать в switch-конструкцию и сделать exhaustive 🚫 Генерируется класс с наследниками. Передав в switch нет подсказок об exhaustive
Value class Класс попадёт в .h-файл, им можно будет пользоваться в Swift 🚫 Класс не попал в .h-файл, пользоваться нельзя
Interfaces
Interface При реализации интерфейса, IDE подставит заглушки для всего Интерфейс стал @protocol-ом. Но почему-то val-свойство превратилось в var
Sealed interface При использовании в switch IDE поможет рассмотреть все варианты 🚫 Сгенерировались отдельные протоколы, не связанные между собой
Fun interface С помощью такого протокола можно более простым синтаксисом описать лямбду 🚫 В Swift нельзя создать анонимный класс
Functions
DSL Надеемся, что DSL в Kotlin-е превратится в DSL на Swift ⚠️ Сгенерировались функции с receiver-ами, выглядит не так удобно, как хотелось бы
Function returns lambda Функция, вернувшая лямбду, работает без крашей; лямбду можно вызвать Реальность совпадает с ожиданием
Function returns primitive type Функция, возвращающая примитивный тип, работает без ошибок Реальность совпадает с ожиданием
Function with extension function as args Можно вызвать функцию так же, как в Kotlin ⚠️ Extension-функция превращается в лямбду с параметром
Function with lambda arguments Функция, принимающая в аргументах одну или несколько лямбд, нормально конвертируется в Swift Реальность совпадает с ожиданием
Function with no return type Функции, которые ничего не возвращают, можно спокойно вызвать Реальность совпадает с ожиданием
Function with value class parameter Функция появится в .h-файле и её можно будет использовать, передавая value-класс 🚫 Функция появилась в .h-файле, но аргумент value-класса развернулся в примитивы
Function with vararg parameter vararg смапился в Swift-овый variardic и используется аналогично 🚫 Не работает так, как ожидается
Functions with overloads Использование перегруженных функций ничем не отличается от Kotlin-а ⚠️ Есть особенности при использовании одинаковых имён параметров
Inline functions Инлайн-функции есть в .h-файле, их можно вызвать Реальность совпадает с ожиданием
Suspend functions Suspend-функции развернулись в удобную для Swift-конструкцию ⚠️ Транслируется в callback, экспериментально - в async / await. Но для использования в реактивных фреймворках требуются дополнительный bridge-код
Generics
Generic classes Сгенерируется класс с generic-ом, пользоваться можно как в Kotlin ⚠️ Есть некоторые особенности использования типов
Generic functions Обычная функция-generic позволяет принять аргумент любого типа 🚫 Нет автоматического вывода типа, особенности nullability
Generic interfaces Можно реализовать протокол с generic-ом после перехода в Swift 🚫 Generic-и на интерфейсах не поддерживаются
Bounded generics Ограничение типа generic-а, объявленное в Kotlin, сработает и в Swift 🚫 Ограничение не сработало
Contravariant generics При указании ключевого слова in на generic-е, сгенерируется generic со схожим поведением (контравариантный generic) 🚫 Не работает как ожидается, приходится использовать приведение типов
Covariant generics При указании ключевого слова out на generic-е, сгенерируется generic со схожим поведением (ковариантный generic) 🚫 Не работает как ожидается, приходится использовать приведение типов
Star projection Сгенерируется generic со схожим поведением (in Nothing / out Any?) 🚫 Не работает как ожидается, приходится использовать приведение типов
Reified functions Функции с reified нормально вызываются из Swift + работают ожидаемым образом 🚫 В рантайме функция крашится

Сравнение Flutter и Swift. Какой стек лучше в 2021 году?

Сегодня существует приложение, кажется, для всего. Если у какой-то компании нет своего приложения — это кажется так же странно, как если бы 10 лет назад у неё не было сайта. В итоге это может обернуться упущенной прибылью, потому что спрос на надежные, дружественные к пользователю приложения никогда ещё не был так высок. К счастью, современные средства разработки для мобильных устройств позволяют легко создавать высокопроизводительные приложения для iOS и Android.

Однако чтобы разработать приложение, нужно сначала решить, какой стек технологий использовать. Если речь идёт про экосистему iOS, то выбор будет стоять между Flutter/Dart или нативной разработкой на Swift. Мы провели сравнение этих технологий, чтобы помочь вам выбрать лучшую для вашего проекта.

Обзор Flutter и Swift в 2021 году

В 2014 году Apple выпустила Swift — мультипарадигмальный, компилируемый язык программирования с открытым исходным кодом, созданный специально для разработки под iOS.

У Swift множество преимуществ:

  • качественная документация;
  • исходный код под свободной лицензией;
  • читаемый синтаксис
  • высокая производительность;
  • современные фичи;
  • поддержка динамических библиотек.

Flutter — кросс-платформенный открытый SDK для мобильных приложений, разработанный в Google. Он использует язык программирования Dart и позволяет создавать приложения для iOS, Android, Linux, Windows, Mac, Google Fuchsia, а также веб-приложения. Он предоставляет те же возможности, что и Swift, и не только:

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

Скорость компиляции Flutter и Swift

Скорость сборки приложения на нативном компилируемом языке почти всегда выше, так что если сравнивать Flutter с Kotlin или Swift, последние почти наверняка будут быстрее — если учитывать именно время «холодной» сборки. Однако в сравнении скорости инкрементальной компиляции, то Dart более конкурентоспособен.

Скорость разработки

Здесь явно в пользу Flutter. Очень немногие компании ограничиваются приложением только для iOS, а если ваше приложения написано на Swift, то под Android придется писать отдельную версию. Разработка двух разных версий приложения может оказаться весьма дорогим процессом.

Flutter позволяет разрабатывать кросс-платформенные приложения и компилировать один и тот же код под несколько платформ. Приложения будут прекрасно работать на разных операционных системах и устройствах, что сэкономит вам время и деньги.

Кроме того, Flutter ускоряет сам процесс. Для него существуют несколько IDE, которые могут сделать разработку быстрее. Его поддерживает Visual Studio Code, которая предоставляет большинство функций Android Studio и IntelliJ, но требует куда меньше ресурсов. Минимальный прототип можно разработать за пару месяцев и потом добавлять в него функции, а не ждать разработки полноценного приложения полгода и более.

Дополнения и переиспользование кода

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

Производительность

Если у вас хватает бюджета на разработку отдельного приложения под каждую платформу, то с точки зрения производительности Swift — отличный выбор, потому что нативные средства помогают использовать ресурсы устройств по максимуму. Но и у кроссплатформенной разработки нет проблем с производительностью

Приложения на Flutter сравнимы с нативными по производительности, поскольку они компилируются в нативный код и не требуют интерпретатора. Кроме того, пакет анимаций для Flutter позволяет легко создавать элегантные и интуитивно-понятные интерфейсы. Большинство встроенных анимационных эффектов также можно модифицировать под нужды конкретного приложения.

Популярность и сценарии использования

В опросе Stackoverflow 2020 года Flutter оказался в тройке самых популярных инструментов разработки. У Flutter 118 тысяч звезд на Github, против 55 тысяч у Swift. Но победителя тут нет — оба стека широко используются во многих известных компаниях. Вот примеры приложений на Swift и Flutter:

На Swift были созданы:

  • Linkedin
  • SlideShare
  • Lyft
  • Firefox
  • Eventbrite

Приложения, написанные на Flutter:

  • Google Ads
  • Alibaba
  • Square
  • Ebay
  • Hamilton Musical
  • Reflectly
  • Groupon
  • Cryptomaniac
  • SpaceX Go
  • Realtor.com

Flutter подходит для самых разных областей, включая розничную торговлю, финансы, оптовые поставки, франчайзинг и здравоохранение.

Однако при выборе между Swift и Dart нужно учитывать некоторые ограничения Flutter. К примеру, Flutter не лучший вариант, если:

Размер приложения не должен превышать 1–3 мегабайта. Приложения на Flutter обычно «тяжелее» нативных.

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

Вы разрабатываете большую игру вроде PUBG. Flutter проектировался для приложений, а не для игр, хотя и подходит для несложных механик.

Возможности Flutter для приложений под iOS

Кажется, что раз Swift создан Apple, то у него преимущество в доступе к возможностям устройства. Но это не так. Множество функций легко интегрируются и в приложения на Flutter:

Apple HealthKit — позволяет приложениям получать данные о здоровье и физической активности пользователя и добавлять новые данные в приложение Health.

Machine learning — позволяет использовать возможности устройств по машинному обучению для разработки инновационных функций.

HomeKit — позволяет пользователям без проблем взаимодействовать с системами «умного дома» и управлять им с помощью Siri.

Flutter Audio

Некоторые возможности для Flutter, впрочем, недоступны. Когда мы разрабатывали приложение Medcorder для нашего клиента, у нас возникла проблема: не существовало способа записи голоса с помощью API, которые предоставляет Google. Наш клиент предложил разработать дополнение к Flutter для этой цели и опубликовать его под свободной лицензией, и мы создали Flutter Audio, о котором вы можете прочитать в нашей статье.

Заключение

Итого: если у вас ограничен бюджет, а механики приложения несложные — Flutter подойдёт отлично. Если же бюджет позволяет развернуться или архитектура приложения сложная, то Swift подойдёт лучше.

Swift — отличная платформа, хотя и у Flutter есть ряд преимуществ, включая возможность разработки под множество платформ сразу. Нативная разработка безусловно хороша, но Flutter непрерывно развивается и, возможно, превзойдет Swift.

Если вы не знаете как выбрать мобильную кросс-платформу в 2021 году или ищете команду разработки для запуска своего мобильного приложения на всех платформах сразу, свяжитесь с нами через форму внизу, и мы расскажем, как использование Flutter поможет вам сэкономить время и деньги.

О Swift - язык программирования Swift (Swift 5.5)

Swift - отличный способ писать программное обеспечение, будь то для телефонов, настольных компьютеров, серверов или чего-либо еще, что запускает код. Это безопасный, быстрый и интерактивный язык программирования, который сочетает в себе лучшее из современного языкового мышления с мудростью более широкой инженерной культуры Apple и разнообразным вкладом сообщества разработчиков ПО с открытым исходным кодом. Компилятор оптимизирован для производительности, а язык оптимизирован для разработки без ущерба для производительности.

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

Swift определяет большие классы распространенных ошибок программирования, принимая современные шаблоны программирования:

  • Переменные всегда инициализируются перед использованием.
  • Индексы массива проверяются на наличие ошибок, выходящих за границы.
  • Целые числа проверяются на переполнение.
  • Опции обеспечивают явную обработку значений nil .
  • Память управляется автоматически.
  • Обработка ошибок позволяет осуществлять контролируемое восстановление после неожиданных сбоев.

Код Swift скомпилирован и оптимизирован для получения максимальной отдачи от современного оборудования. Синтаксис и стандартная библиотека были разработаны на основе руководящего принципа, согласно которому очевидный способ написания кода также должен работать наилучшим образом.Сочетание безопасности и скорости делает Swift отличным выбором для всего, начиная с «Hello, world!» ко всей операционной системе.

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

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

Бета Программное обеспечение

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

Подробнее об использовании бета-версии программного обеспечения Apple

SwiftDocOrg / swift-doc: генератор документации для проектов Swift

Пакет для создания документации для проектов Swift.

Учитывая каталог файлов Swift, swift-doc создает файлы HTML или CommonMark (Markdown) для каждого класса, структуры, перечисления и протокола а также псевдонимы типов верхнего уровня, функции и переменные.

Пример вывода

Требования

Утилита командной строки

swift-doc можно использовать из командной строки в macOS и Linux.

Установка

Домашнее пиво

Выполните следующую команду для установки с помощью Homebrew:

 $ brew установить swiftdocorg / формулы / swift-doc 

Если у вас уже установлен swift-doc , выполните следующую команду, чтобы обновить вашу установку:

В случае сбоя установки или обновления появляется сообщение Ошибка: не удалось загрузить ресурс swift-doc , попробуйте сбросить установку с помощью следующих команд:

 $ brew удалить swift-doc
$ brew untap swiftdocorg / формулы
$ brew install swiftdocorg / формулы / swift-doc 
Докер

Вы можете запустить swift-doc из последнего образа Docker с помощью следующих команд:

  $ docker pull swiftdoc / swift-doc: последний
$ docker запустить -it swiftdoc / swift-doc
  
Вручную

Выполните следующие команды для сборки и установки вручную:

  $ git clone https: // github.com / SwiftDocOrg / swift-doc
$ cd swift-doc
$ make install
  

Если вы используете Ubuntu Linux, вам может потребоваться сначала установить необходимые компоненты выполнив следующую команду:

  $ apt-get update
$ apt-get install -y libxml2-dev graphviz
  

Использование

  ОБЗОР: Утилита для создания документации для кода Swift.

ИСПОЛЬЗОВАНИЕ: swift doc <подкоманда>

ПАРАМЕТРЫ:
  --version Показать версию.
  -h, --help Показать справочную информацию.ПОДКОМАНДЫ:
  генерировать Создает документацию Swift
  покрытие Создает статистику покрытия документации для Swift
                          файлы
  диаграмма Создает диаграмму отношений символов Swift
  

Примечание : Драйвер swift обеспечивает расширяемость с помощью подкоманд. Если вы наберете неизвестную подкоманду, например swift foo , система ищет команду swift-foo в вашем PATH .Этот механизм позволяет запускать swift-doc либо напрямую, либо как swift-doc .

swift-doc сгенерировать
  ОБЗОР: Создание документации Swift

ИСПОЛЬЗОВАНИЕ: swift doc generate [ ...] --module-name  [--output ] [--format ] [--base-url  ]

АРГУМЕНТЫ:
   Один или несколько путей к каталогу, содержащему файлы Swift.

ПАРАМЕТРЫ:
  -n, --module-name <имя-модуля>
                          Название модуля
  -o, --output  Путь для сгенерированного вывода (по умолчанию:
                          .сборка / документация)
  -f, --format  Формат вывода (по умолчанию: commonmark)
  --base-url  Базовый URL-адрес, используемый для всех относительных URL-адресов в сгенерированном
                          документы. (дефолт: /)
  --minimum-access-level <минимальный-доступ-уровень>
                          Минимальный уровень доступа символов, который должен
                          быть включенным. (по умолчанию: общедоступный)
  -h, --help Показать справочную информацию.
  

Подкоманда generate берет один или несколько путей и рекурсивно перечисляет их, сбор всех файлов Swift в один «модуль» и соответствующим образом сформировать документацию.Все скрытые каталоги пропускаются, включая .git и другие каталоги с путями, начинающимися с точки (. ). Тесты верхнего уровня также пропускаются каталоги .

  $ swift doc генерировать путь / к / SwiftProject - имя-модуля SwiftProject
$ tree .build / документация
$ documentation /
├── Дом
├── (...)
├── _Footer.md
└── _Sidebar.md
  

По умолчанию выходные файлы записываются в .build / documentation в формате CommonMark / GitHub Wiki, но вы можете изменить это с помощью флагов опций --output и --format .

  $ swift doc generate path / to / SwiftProject / Sources --module-name SwiftProject --output Documentation --format html
$ Документация /
├── (...)
└── index.html
  

По умолчанию swift-doc включает только символы, объявленные как public или open в сгенерированной документации. Чтобы включить внутренних или частных объявлений , передать --minimum-access-level флаг с указанным уровнем доступа.

покрытие swift-doc
  ОБЗОР: Создает статистику охвата документации для файлов Swift

ИСПОЛЬЗОВАНИЕ: быстрое покрытие документов [ ...] [--output ]

АРГУМЕНТЫ:
   Один или несколько путей к каталогу, содержащему файлы Swift.

ПАРАМЕТРЫ:
  -o, --output  Путь к сгенерированному отчету
  --minimum-access-level <минимальный-доступ-уровень>
                          Минимальный уровень доступа символов, который должен
                          быть включенным.(по умолчанию: общедоступный)
  -h, --help Показать справочную информацию.
  

Подкоманда покрытия генерирует статистику покрытия документации для файлов Swift.

  $ git clone https://github.com/SwiftDocOrg/SwiftSemantics.git

$ swift run swift-doc охват SwiftSemantics / Sources --output "dcov.json"
$ cat dcov.json | jq ".data.totals"
{
  «count»: 207,
  «задокументировано»: 199,
  «проценты»: 96.1352657004831
}

$ cat dcov.json | jq ".data.symbols [] | select (.задокументировано == ложь) "
{
  "file": "SwiftSemantics / Supporting Types / GenericRequirement.swift",
  «строка»: 67,
  «столбец»: 6,
  "name": "GenericRequirement.init? (_ :)",
  "type": "Инициализатор",
  "задокументировано": ложь
}
...
  

Хотя существует множество инструментов для оценки тестового покрытия кода, Ничего подобного по охвату документации найти не удалось. К этому концу, мы придумали простой формат JSON вдохновлен llvm-cov.

Если вам известен существующий стандарт которые, по вашему мнению, могут лучше подходить для этой цели, пожалуйста, свяжитесь с нами, открыв вопрос!

swift-doc схема
  ОБЗОР: Создает диаграмму отношений символов Swift

ИСПОЛЬЗОВАНИЕ: swift doc diagram [...]

АРГУМЕНТЫ:
   Один или несколько путей к каталогу, содержащему файлы Swift.

ПАРАМЕТРЫ:
  --minimum-access-level <минимальный-доступ-уровень>
                          Минимальный уровень доступа символов, который должен
                          быть включенным. (по умолчанию: общедоступный)
  -h, --help Показать справочную информацию.
  

Подкоманда диаграммы формирует график API в формате DOT который может быть отображен GraphViz в диаграмму.

  $ swift run диаграмма swift-doc Alamofire / Source> Alamofire.gv
$ head Alamofire.gv
digraph Anonymous {
  «Сессия» [shape = box];
  "NetworkReachabilityManager" [shape = box];
  "URLEncodedFormEncoder" [форма = коробка, периферия = 2];
  "ServerTrustManager" [shape = box];
  "MultipartFormData" [shape = box];

  subgraph cluster_Request {
    «Запрос данных» [shape = box];
    «Запрос» [shape = box];

$ dot -T svg Alamofire.gv> Alamofire.svg
  

Вот отрывок из графика, созданного для Alamofire:

Действие GitHub

В этом репозитории также размещается действие GitHub. которые вы можете включить в рабочий процесс своего проекта.

Файлы CommonMark, созданные с помощью swift-doc отформатированы для публикации на GitHub Wiki вашего проекта, что вы можете сделать с github-wiki-publish-action. В качестве альтернативы, вы можете указать формат HTML для публикации документации в Страницы GitHub или объединить их в артефакт выпуска.

Входы

  • входов : Путь к каталогу, содержащему файлы Swift ( .swift ) в вашей рабочей области. (По умолчанию: "./Sources" )
  • формат : Формат вывода ( «commonmark» или «html» ) (По умолчанию: "commonmark" )
  • имя модуля : Имя модуля.
  • базовый URL : Базовый URL-адрес для всех относительных URL-адресов, созданных в документах. (По умолчанию: "/ )
  • вывод : Путь для сгенерированного вывода. (По умолчанию: "./.build/documentation" )

Пример рабочего процесса

 # .github / workflows / documentation.yml
имя: Документация

on: [push]

вакансии:
  строить:
    запускается: ubuntu-latest

    шаги:
      - использует: actions / checkout @ v1
      - имя: Создать документацию
        использует: SwiftDocOrg / swift-doc @ master
        с участием:
          входы: «Источники»
          имя-модуля: MyLibrary
          вывод: «Документация»
      - name: Загрузить документацию в Wiki
        использует: SwiftDocOrg / github-wiki-publish-action @ v1
        с участием:
          путь: "Документация"
        env:
          GH_PERSONAL_ACCESS_TOKEN: $ {{секреты.GH_PERSONAL_ACCESS_TOKEN}} 

Развитие

Веб-активы

ресурсов CSS, используемых в формате вывода HTML. обрабатываются и генерируются PostCSS. Чтобы внести изменения в эти объекты, вам понадобится Node.js и менеджер пакетов, например npm , установлен на вашем компьютере.

Перейдите в каталог .node и запустите npm install , чтобы загрузить необходимые инструменты и библиотеки.

Примечание : упаковка.json находится в скрытом подкаталоге .node чтобы запретить Xcode отображать или индексировать содержимое node_modules при открытии основного проекта.

Из каталога .node , запустите сценарий watch , чтобы начать следить за изменениями файлов в папке Assets . Каждый раз, когда исходный файл ресурса добавляется, удаляется или обновляется, соответствующий (неоптимизированный) продукт создается автоматически в папке Sources / swift-doc / Generated .

Когда результат вас устраивает, зафиксировать любые изменения в исходных файлах в Assets а также сгенерированные файлы в Sources / swift-doc / Generated .

  $ git add Assets Sources / swift-doc / Сгенерировано
$ git commit
  

Процесс выпуска

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

Выполните следующие действия, чтобы выпустить новую версию swift-doc :

Известные проблемы

  • Xcode не может запускать модульные тесты ( U ) при открытии пакета swift-doc напрямую, в отличие от первого создания файла проекта Xcode с быстрый пакет generate-xcodeproj . (Сообщенная ошибка: Библиотека не загружена: @ rpath / lib_InternalSwiftSyntaxParser.dylib ). В качестве обходного пути вы можете установить последнюю версию инструментария и включите его в «Xcode> Preferences> Components> Toolchains».В качестве альтернативы, вы можете запускать модульные тесты из командной строки с быстрым тестом .

Лицензия

MIT

Контакт

Мэтт (@mattt)

Как документировать свой проект с помощью DocC - Взлом с помощью Swift

DocC - это новый инструмент Apple для создания красивой, интерактивной и понятной документации прямо из вашего кода, который легко интегрируется как в Xcode, так и в Интернет.

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

Прежде чем я начну, вот несколько основ:

  • У вас должен быть установлен Xcode 13, чтобы иметь доступ к DocC.
  • В настоящее время он поддерживает только Swift. Они уже получили запросы на добавление поддержки Objective-C, и я надеюсь, что в долгосрочной перспективе они добавят поддержку и для других языков.
  • Если вам было интересно, DocC - это сокращение от «Documentation Compiler», и произносится с двумя одинаково подчеркнутыми слогами - «Doc-See» в отличие от «doxy».
  • Xcode содержит множество важных новых функций - это еще один действительно выдающийся год, и я надеюсь, что команда действительно гордится. Вы можете узнать больше в моей статье Что нового в Xcode 13.

Имейте в виду, что я использую Xcode 13 beta 1, так что на данный момент все только начинается - я ожидаю, что DocC будет сильно доработан перед финальной версией в конце этого года.

Спонсируйте взлом со Swift и войдите в крупнейшее в мире сообщество Swift!

Во-первых, что такое DoC

, а не

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

Если вы хотите попробовать это в своем собственном проекте приложения, просто перейдите в меню «Продукт» и выберите «Сборка документации».Это может занять минуту или две, но когда все будет готово, вы увидите окно Apple Developer Documentation с его результатами - документацию вашего приложения, живущую рядом с собственными фреймворками Apple.

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

Если вы попали в такую ​​ситуацию, я бы посоветовал вам разбить ваш проект на более мелкие пакеты - это должно позволить DocC правильно сканировать и документировать их.

Моя следующая попытка была с моим проектом Sitrep, который - это пакет. Я был уверен, что это будет работать намного лучше, но снова возникли проблемы: DocC будет сканировать только те вещи, которые доступны для внешнего пакета, поэтому большая часть Sitrep игнорируется. Это не ошибка, а еще один разрыв между моей головой и тем, как работает DocC - он очень сильно ориентирован на людей, которые используют пакет или фреймворк, в отличие от людей, создающих этот пакет или фреймворк, или даже приложение.

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

Работа с документацией Markdown

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

Хотя этот пакет действительно имеет некоторые внутренние функции, он в основном представлен миру как общедоступный API, и это именно то, что ищет DocC. И прямо из коробки - просто перейдя в Product> Build Documentation - мы действительно получаем кое-что очень хорошее:

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

Фактически, документация практически неотличима от собственной документации для разработчиков Apple - вплоть до сообщения «Обзор недоступен», когда чего-то не хватает.

Все это работает из коробки благодаря комментариям документации, которые представляют собой комментарии Xcode, написанные в определенном формате: либо с использованием тройной косой черты, /// , либо начиная с / ** .

Комментарии Markdown - это , а не , такие же, как обычные встроенные комментарии, которые вы добавляете в конкретный код, поэтому вам нужно использовать их по-другому:

  • Обычные комментарии, // и / * , используются для обозначения того, что пытается сделать ваш код, с добавлением объяснений для людей, которые хотят понять или изменить этот фрагмент кода.
  • Комментарии к документации, /// и / ** , используются для обозначения того, как следует использовать ваш код, объясняя, каковы его параметры, что он возвращает и многое другое.

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

Лучший способ начать работу с документацией Markdown - выбрать функцию, которую нужно задокументировать, нажать Shift + Cmd + A, чтобы открыть всплывающее окно действий кода, затем выбрать Добавить документацию.Если вы похожи на меня и предпочитаете сочетания клавиш, используйте Opt + Cmd + /, чтобы получить тот же результат.

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

  Поместите текст в `обратные кавычки`, чтобы отметить фрагменты кода.
DocC также поддерживает doubleBackticks для создания ссылок на другие части вашей документации и пути, например SomeClass / someProperty, чтобы быть более конкретными.* Пишите маркеры, начиная со звездочки и затем пробела.
    * Отступайте звездочки для создания подсписок
1. Вы можете написать пронумерованный список, начиная с 1.
1. Последующие элементы могут быть пронумерованы, если хотите, но вы также можете пронумеровать их 1. и Xcode изменит их нумерацию за вас.

# Заголовки начинаются с символа #
Если вам нужны подзаголовки, используйте ##, ### и так далее.

Для ссылок [поместите текст в квадратные скобки] (а вашу ссылку в скобки).
Напишите * одну звездочку * вокруг слов, чтобы сделать их курсивом.
Напишите ** две звездочки ** вокруг слов, чтобы выделить их жирным шрифтом.
Напишите *** три звездочки *** вокруг слов, чтобы выделить их жирным шрифтом и курсивом одновременно  

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

Например, ключевое слово Returns позволяет указать, какое значение вызывающий может ожидать в ответ при успешном выполнении функции. Это не просто тип данных - Xcode может сам это выяснить, - а значение в . Так, например, вы можете сказать это:

  - Возвращает: строка, содержащая дату в формате RFC-822  

Существует также ключевое слово Parameter , которое позволяет указать имя параметра и описать, что он содержит.Вы можете включить столько строк Parameter , сколько у вас есть параметров, просто перечислив их каждую вместе с тем, что они есть на самом деле:

  - Альбом параметров: Название альбома Тейлор Свифт
- Параметр дорожки: номер дорожки для загрузки  

Опять же, Xcode может определить тип параметра, поэтому вы просто документируете то, что он представляет.

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

  - Выдает: LoadError.networkFailed, LoadError.writeFailed  

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

Добавление каталога документации

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

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

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

Чтобы сделать это в своем собственном проекте, щелкните правой кнопкой мыши каталог вашего пакета в навигаторе проекта, затем выберите «Новый файл». Если вы прокрутите вниз до раздела «Документация», вы увидите «Каталог документации» - выберите его и нажмите «Далее», и Xcode немедленно создаст каталог для вас.

Xcode создаст для вас каталог документации, который называется «Документация». Внутри он создаст один файл Markdown, который также несколько бесполезно называется Documentation, а также каталог ресурсов, в котором вы можете разместить ресурсы, такие как снимки экрана.

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

  # SwiftGD  

Затем вы можете продолжить и написать бесплатную Markdown ниже, но осторожно - вы получите контроль над своим резюме, обзором и всеми темами, которые хотите перечислить, но вы должны следовать определенному формату:

  • Не трогайте заголовок «Темы».Если вы измените его имя, результат будет выглядеть странно, а если вы попытаетесь добавить еще один заголовок второго уровня, это не сработает.
  • Заголовки третьего уровня - «Группа» по умолчанию - становятся выровненными по левому краю заголовками, которые располагаются рядом с объектами, которые вы хотите выделить.
  • Внутри заголовков третьего уровня вы можете размещать маркированные ссылки на статьи, которые хотите упомянуть. Не пытайтесь размещать там ничего, кроме ссылок на другие объекты, потому что это не сработает.

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

Важно: Помните, что ссылки похожи на обычный код Markdown, за исключением использования двойных обратных кавычек.

Например, в моем проекте SwiftGD я мог бы выбрать некоторые конкретные типы, которые важны, например:

  - `` Цвет ''
- `` Прямоугольник ''  

Или я мог бы указать на определенные свойства типа, например:

  - `` Прямоугольник / точка ''
- `` Прямоугольник / размер ''  

Вы могли заметить, что Xcode достаточно умен, чтобы выполнять здесь автозавершение кода, что действительно полезно при работе с методами, потому что вы просто вводите их полностью, с именами параметров:

  - `` Image / applyInterpolation (enabled: currentSize: newSize:) ''  

Во время сборки эти ссылки расширяются до полных ссылок на документацию, которые переходят на всю страницу, а также предоставляют любой сводный текст ниже, если это возможно.

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

Важно: Если вы обнаружите, что ваши изменения не видны, возможно, вам нужно увеличить swift-tools-version в файле Package.swift. SwiftGD был установлен на 5.0 и поэтому не работал с DocC, но повышение этого значения до 5.5 решило проблему.

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

Чтобы добавить изображение, сначала дайте ему имя, поясняющее, для чего оно предназначено. Apple рекомендует использовать изображения @ 2x по всем направлениям, поэтому, по крайней мере, вам необходимо предоставить [email protected] Однако, если вам нужно одно изображение для светлого режима, а другое для темного, вы можете предоставить темный вариант, поместив «~ dark» перед @ 2x, чтобы получился [email protected]

Подобные волшебные имена файлов были обычным явлением в разработке для iOS до того, как у нас появился доступ к каталогам ресурсов, и, честно говоря, я бы тоже хотел видеть их здесь - управление активами становится сложной задачей в нетривиальном проекте, и любые инструменты, которые могут помочь, приветствуются.

В любом случае, чтобы встроить это изображение в статью, используйте стандартный синтаксис изображения Markdown:

 ! [Взлом с логотипом Swift] (hws.png)  

В этом небольшом фрагменте обратите внимание на то, что нам не нужно добавлять данные о вариантах изображения к имени файла - достаточно простого старого hws.png - а также важно добавить описание, чтобы VoiceOver мог описывать содержимое изображения.

Если вы продолжите и создадите свою документацию заново, вы должны увидеть картинку на месте.В бета-версии 1 кажется, что переключение между светлым и темным режимами не совсем безупречно - вы можете обнаружить, что вам нужно переключаться между статьями, чтобы обновить изображение.

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

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

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

А сейчас выберите «Файл статьи», который позволит нам создать еще одну статью с произвольным текстом. Как и в нашей исходной статье, она может содержать всю разметку, которую вы хотите, включая ссылки на другие статьи и API, которые вы хотите упомянуть.

Имя , которое вы даете этой новой статье, имеет значение, потому что оно влияет на то, как вы будете ссылаться на нее в другом месте.Вы можете использовать пробелы, чтобы получить более естественные имена, если хотите; они просто будут заменены тире во время сборки.

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

.
    

Опять же, Xcode сделает это за вас автоматически и даже проверит, добавили ли вы неработающую ссылку случайно - вы получите предупреждение прямо в своем файле Markdown.(PS: ребята из Xcode: это может быть ошибка? Спасибо!)

Распространение вашей работы

Все это время мы продвигали нашу работу непосредственно в средство просмотра документации Xcode, но это временно - как только вы закроете Xcode, он исчезнет оттуда. Пока вы работаете, полезно знать, что все это исчезнет, ​​как только вы бросите курить, но, очевидно, в какой-то момент у вас будет то, чем вы действительно захотите поделиться с остальным миром.

Вы можете, если хотите автоматически создать свой пакет документации, используя xcodebuild , но вы также можете щелкнуть его правой кнопкой мыши прямо в средстве просмотра документации и выбрать «Экспорт».Как только вы это сделаете, вы получите пакет «.doccarchive» - в нем нет ничего особенного, просто каталог, в котором нужно прочитать вашу документацию в Xcode или в Интернете.

Итак, теперь вы можете заархивировать это и отправить кому-нибудь для просмотра или, если вы хотите, опубликовать в Интернете. Теперь, если вы похожи на меня, то, вероятно, знаете, что Python имеет встроенный модуль веб-сервера, который действительно полезен для быстрого тестирования - вы должны запустить python3 -m http.server в каталоге.

Однако это не работает: генерируемый ими пакет требует очень специфической конфигурации сервера.(css | js | data | images | downloads | favicon \ .ico | favicon \ .svg | img | theme-settings \ .json | videos) \ /.*$ YourPackage.doccarchive / $ 0 [L]

После того, как у вас есть это в файле htaccess на вашем веб-сервере, который, очевидно, настроен так, чтобы YourPackage.doccarchive соответствовал вашему имени файла, вы сможете копировать через архив документации, и все будет более или менее работать.

Чтобы попробовать, я установил http://docc.hackingwithswift.com - он фактически не работает как ссылка, потому что это локальный веб-сервер, работающий на моем Mac с использованием MAMP.Хотя архив должен обслуживаться из корня веб-сайта, он не берет на себя остальную часть вашего сайта - вам все равно придется обслуживать остальные страницы самостоятельно, и он позаботится только о таких, как http: // docc.hackingwithswift.com/documentation/SwiftGD в моем случае.

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

В настоящее время сгенерированная документация представляет собой фактически запечатанную коробку - правило перезаписи Apache ссылается на файл theme-settings.json, что предполагает некоторую настройку, но я не знаю, в какой степени. Я могу представить себе более крупные компании, которые хотят интегрировать свой корпоративный бренд или обычную навигацию по сайту.

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

Куда дальше?

Стоит повторить то, что я сказал в начале: это только бета-версия 1 Xcode 13, так что есть много времени для развития вещей, прежде чем мы выйдем к финальной версии, и даже тогда это только начало - я ожидаю, что DocC продолжать развиваться и расти в будущем по мере добавления новых функций.

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

Нам еще предстоит увидеть, как DocC адаптируется к другим языкам программирования, не в последнюю очередь к Objective-C. Люди из Apple в Twitter и на форумах разработчиков заявили, что это приоритетная задача, которая во многом поможет DocC добиться более широкого распространения.

Уже есть инструменты, которые выполняют аналогичные задачи, но ни один из них не настолько интегрирован. Я поговорил с JP Simard, который создал широко популярный инструмент Jazzy еще в 2015 году, а также со многими другими - он выполняет ту же работу, что и DocC, за исключением того, что является открытым исходным кодом, управляемым сообществом, поддерживает Objective-C и работает с частными символами.

Как отметил JP, сильная сторона DocC заключается в том, что он выходит за рамки простого создания документации:

«Я действительно рад, что Apple предоставляет инструмент для создания документации по коду, и это больше, чем просто инструмент - это пользовательский интерфейс программы просмотра, интеграция Xcode с командой сборки документации, интеграция с быстрой справкой, а также интерфейс командной строки. На выходе есть статический HTML-сайт, который вы можете разместить самостоятельно и просматривать в веб-браузере, но, что еще лучше, все данные, отображаемые в расширенном пользовательском интерфейсе, также доступны в машиночитаемом формате JSON, поэтому существующие инструменты создания документации, такие как Jazzy и SwiftDoc можно легко добавить поддержку приема этих данных.”

Одним из интересных преимуществ DocC является его способность создавать интерактивные учебные пособия, идентичные тем, которые Apple использует для SwiftUI. Хотя я пока не вижу, что я использую их, я обязательно буду следить за тем, проявляет ли сообщество интерес к этому формату.

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

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

Вы, , планируете перейти на DocC, или в нем отсутствует функция, на которую вы полагаетесь? Дайте мне знать в Twitter @twostraws!

Спонсируйте взлом со Swift и войдите в крупнейшее в мире сообщество Swift!

Правильное документирование кода в Xcode - PeterWitham

Начиная с

Xcode 7, мы получили возможность документировать наш код, не ограничиваясь простыми комментариями.Используя Markdown, мы можем писать структурированные документы, которые доступны как прямо в редакторе Xcode, так и как отдельная документация.

Мы можем использовать эту функцию для документирования классов, функций, параметров, буквально всего, что, по нашему мнению, требует объяснения или ссылки. Это позволяет нам лучше делиться кодом с членами команды или возвращаться в будущем к тому, что что-то делает и почему.

Если вы пишете API, которые будут использоваться другими разработчиками, документация является обязательной!

Чтобы в полной мере воспользоваться богатой документацией, вам необходимо понимать хотя бы основы Markdown.У Apple также есть справочный документ, который вы можете прочитать, чтобы понять, какие теги поддерживаются и как их использовать. Я не буду вдаваться в подробности языка разметки в этой статье.

После того, как вы задокументировали код, он появится на панели инспектора быстрой справки и в редакторе кода. Проработка приведенного ниже примера поможет продемонстрировать это.

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

  • Параметр someParameterName:
  • Возврат:
  • Примечание:
  • См. Также:
  • Задайте:
  • Предупреждение:
  • Версия:
  • Автор:
  • Примечание:

Имена должны объяснять их назначение, например, мы можем указать имя автора в документации функции, чтобы мы знали, кто это написал, вместе с номером версии.

Давайте попробуем на примере и посмотрим, как все это работает на нашу пользу.

Время примера

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

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

Я воспользуюсь сочетанием клавиш Command + Option + / , и код шаблона будет сгенерирован для меня.

Теперь все, что мне нужно сделать, это ввести информацию так же, как если бы я заполнял параметры функций. Постарайтесь сделать ваши комментарии осмысленными, постарайтесь описать цель кода и то, что он будет делать.

Я повторю процесс для функции concatText . На этом документация завершена, я включил код и сгенерированную документацию ниже.

  /// Касание кнопки вызовет _concatText_
/// функция и используйте return для установки отображения
/// метка.
///
/// - Отправитель параметра: _
@IBAction func btnDisplayText (_ отправитель: UIButton) {
lblDisplayText.text = concatText (inputString: txtInput.text!)
}


/// Принимает строковый аргумент и возвращает объединенный
/// Нить.
///
/// - Параметр inputString: Любая строка в качестве ввода
/// - Returns: возвращает новую строку
func concatText (inputString: String) -> String {
let newText = "Текст:" + inputString
вернуть newText
}
  

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

Итак, есть простой пример создания документации по коду. Как видите, это очень полезно, если вы делитесь кодом с командой, и им нужно знать, что что-то делает. Мы все должны задокументировать наш код, это просто немного облегчает нам жизнь и устраняет предлоги, чтобы не делать этого.

Отдельные документы

Используя сторонний инструмент, мы можем создать отдельную документацию, которую можно будет просматривать в веб-браузере. Для этого нам нужно установить инструмент под названием Jazzy .Так что давайте сделаем это очень быстро.

Jazzy - это терминал. Нам нужно установить Ruby gem, поэтому в терминале введите

 $ sudo gem установить jazzy 

Теперь, когда инструмент установлен, перейдите в папку проекта, для которой вы хотите создать документацию, и запустите Jazzy

.
 $ jazzy - min-ac внутренний 

Чтобы увидеть доступные параметры Jazzy и их значение, вы можете использовать справочную систему.

 $ jazzy - помощь 

Jazzy должен был создать папку с именем docs , в ней будет вновь созданная документация, которую вы можете открыть в любом средстве просмотра HTML, например, в веб-браузере.Вы увидите что-то в этом роде, поскольку Jazzy использует

.
  Запуск xcodebuild
Разбор ViewController.swift (1/2)
Разбор AppDelegate.swift (2/2)
13% покрытие документации 13 недокументированными символами
включает 15 внутренних, публичных или открытых символов
строительная площадка
построение поискового индекса
скачивание бейджа покрытия
вставьте ♪ ♫ в свои свежие новые документы в документах
  

Обертка

Итак, это краткое введение в документирование кода в Xcode.Это только начало прекрасного пути к хорошо документированному коду, добро пожаловать на борт.

Я создал репозиторий GitHub с этим примером, чтобы вы могли поиграть с ним, вы можете скачать его здесь.

Документация для проекта Swift и Objective-C с использованием Jazzy | Леонардо Билия | cinqtechnologies

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

С Jazzy это вполне возможно!

Обзор

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

Jazzy генерирует для нас все файлы HTML, , CSS, и JS, . Так что нам не о чем беспокоиться.

Может быть описание классов, перечислений, протоколов, расширений, функций, свойств и многого другого.

Как начать работу с Jazzy?

Просто удерживайте Command + Space , введите Terminal в поиске Spotlight и нажмите , чтобы вернуть .

Теперь введите следующую команду:

 sudo gem install jazzy 

Введите системный пароль и дождитесь завершения процесса.

Пришло время добавить некоторую родную документацию в наш проект Xcode.

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

Здесь вы можете прочитать руководство по Markdown, которое вдохновит вас.

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

Вернитесь в терминал и перейдите в корневую папку проекта, используя следующую команду:

 cd YOUR-PROJECT-ROOT-FOLDER-PATH 

Ах, я почти забыл!
Если вам нужна дополнительная помощь, вы можете использовать:

 jazzy --help 

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

 jazzy --min-acl internal 

И все!

Перейдите в папку проекта Xcode, и вы увидите папку «docs» .
Откройте индекс .html , и вы получите свою блестящую документацию по стилю Apple, которая будет выглядеть так:

Но подождите! Есть ли способ сделать это еще лучше?

Конечно, есть!
Вместо того, чтобы вводить странный код каждый раз, когда вы хотите повторно сгенерировать свои документы. Например:

 jazzy --min-acl internal 

Почему бы не сделать его более естественным, заключив команды и настройки Jazzy в Makefile?

 документация: 
@jazzy \
--min-acl internal \
--no-hide-documentation-охват \
--theme apple \
--output./ docs \
--documentation =. / *. md
@rm -rf ./build

Просто откройте ваш любимый текстовый редактор и создайте новый Makefile с приведенным выше кодом и сохраните его в корневой папке вашего проекта Xcode.

С этого момента мы можем просто запустить приведенный ниже код в Терминале для создания документации.

 make documentation 

Некоторые пояснения:

min-acl internal
Чтобы задокументировать все общедоступные функции и переменные, мы установили для него значение internal .Но если вы хотите также задокументировать и предоставить функции private и fileprivate , min-acl необходимо установить как private.

no-hide-documentation-охват
Включает процентную долю документации проекта в документах.

тема apple
Выберите лучшую тему для своего проекта. Посмотрите примеры ниже:

output ./docs
Это путь вывода сгенерированной документации.

документация =./ * md
И последнее, но не менее важное: мы можем добавить раздел в сгенерированные документы со ссылкой на ReadMe. Итак, мы можем использовать это как домашнюю страницу для документации.

Размещение новых документов на страницах GitHub

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

  1. Ваш проект должен быть общедоступным на Github.
  2. У вас есть учетная запись Github Pro

Прежде всего, зафиксируйте и отправьте свой проект в Github, а затем:

  • Перейдите в настройки Github
  • Прокрутите страницу вниз, пока не найдете раздел для Github Страницы
  • Откройте раскрывающееся меню источника и выберите папку с документами

Вот и все.Вы получите настраиваемый URL-адрес, который можно использовать, чтобы связать страницу ReadMe с вашей новой документацией.

Итак, продолжайте и проверьте тот, который я создал для этого примера.

Проект и документация

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

Создание документации для вашего пакета Swift и размещение на страницах GitHub | Рик Виеренга

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

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

Swift использует особую разновидность Markdown. Если вы еще не знакомы с этим, ознакомьтесь со следующими руководствами:

Короче говоря, вы должны добавить строку Markdown с тройными косыми чертами ( /// ) к каждой общедоступной переменной, функции и классу, объясняя, что это делает.

Одна вещь, о которой не упоминаются в приведенных выше статьях, - это примеры использования - лучший способ документировать что-либо. Итак, давайте посмотрим на это сейчас.

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

Для написания блоков кода я рекомендую вам использовать 4 серьезных акцента: , `` .

Вот типичный пример использования:

source: s5tf-team

А вот как это будет выглядеть на веб-сайте документации:

source: s5tf-team

Конечно, несколько примеров использования тоже работают:

source: s5tf-teamource : s5tf-team

Теперь, когда вы являетесь экспертом в написании комментариев к документации для своего кода, давайте посмотрим, как создавать красивые веб-страницы.

Установка

Установка очень проста с менеджером пакетов Ruby:

 sudo gem install jazzy 

Создание документации

Для создания документации просто запустите jazzy в терминале (вы должны cd в каталог вашего проекта ).

 jazzy 

Jazzy анализирует все ваши файлы и создает веб-страницу для каждого объекта.

Настройка

По умолчанию эти страницы выглядят неплохо, но вы также можете настроить их в соответствии со своими потребностями. Например, допустим, вы хотите разместить ссылку на свою собственную веб-страницу. Для этого можно передать параметр --author_url .

 jazzy \ - author_url http://rickwierenga.com \ 

Хотя это прекрасно работает, когда вы запускаете jazzy локально, он очень быстро испортится, когда вы разместите процесс создания документации на GitHub.А поделиться настройками с другими участниками непросто.

Вместо этого давайте напишем файл .jazzy.yaml , в котором будет размещена ваша конфигурация. Если вы никогда раньше не видели YAML, не волнуйтесь - это как документ Word.

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

 author_url: http://rickwierenga.com 

Давайте добавим еще несколько свойств:

 author_url: http: // rickwierenga.com 
автор: Рик Виеренга
github_url: https: // github.com / rickwierenga /
тема: полная ширина

Примечание тема ? Да, Jazzy поддерживает разные темы!

Чтобы получить полный список параметров конфигурации, выполните:

 jazzy --help config 

Просмотр ваших документов локально

Перед тем, как нажимать на GitHub, всегда рекомендуется проверить, работает ли ваш код. В данном случае это означает проверку правильности создания вашей документации.

Вы можете просмотреть документацию в Safari, набрав open docs / index.html в терминале. Если при этом открывается не Safari, а текстовый редактор, например, введите open docs , откроется окно Finder. Затем найдите index.html и перетащите его в Safari.

Обратите внимание, что вам не следует помещать папку docs в GitHub, потому что ваша документация будет размещена в отдельной ветке. Так что папка docs только сбивает с толку. Более того, это, вероятно, вызовет множество нежелательных конфликтов слияния. Лучше добавить в свой .gitignore файл.

Чтобы разместить что-либо на страницах GitHub, вам необходимо создать свою собственную домашнюю страницу.

a) У меня уже есть страница GitHub Pages

Если у вас уже есть страница GitHub Pages, это здорово! Вы можете сохранить свою домашнюю страницу, и GitHub автоматически разместит ваши документы по адресу example.github.io/your_package .

б) У меня еще нет страницы GitHub Pages

Если у вас нет страницы GitHub Pages, вы можете очень легко ее создать, создав новый репозиторий GitHub под названием .github.io . Вы должны установить флажок « Инициализировать этот репозиторий с помощью README » при создании.

Через пару минут вы можете посетить .github.io в своем любимом браузере, чтобы увидеть свою личную страницу.

Для получения дополнительной информации перейдите по следующим ссылкам:

Для запуска GitHub Actions ваша библиотека должна быть общедоступной . GitHub предоставляет вам бесплатные вычисления для macOS в обмен на ваши усилия по внесению вклада в открытый исходный код ❤️

Для автоматического запуска jazzy мы будем использовать предварительно настроенное действие GitHub под названием «Опубликовать Jazzy Docs», доступное здесь:

  1. Перейдите на github .ru / <ваше-имя-пользователя> / <ваш-пакет> / actions / new .
  2. В правом верхнем углу выберите «Самостоятельная настройка рабочего процесса».

Откроется редактор действий GitHub. Опять же, это файл yaml.

3. Следующий код будет хорошим началом.

 имя: PublishDocumentationon: 
выпуск:
типы: [опубликованные] задания:
deploy_docs:
запускается: macOS-latest
шаги:
- использует: actions / checkout @ v1
- name: Publish Jazzy Docs
использует: steven0351 / publish-jazzy-docs @ v1
с:
personal_access_token: $ {{секреты.ACCESS_TOKEN}}
config: .jazzy.yaml

Это действие запускается автоматически, если вы создаете новый выпуск. Он также использует ваш файл .jazzy.yaml для загрузки конфигурации.

Вы можете изменить

 на: 
выпуске:
типах: [опубликовано]

на

 на: [push] 

для запуска регенерации документации при каждой фиксации.

Если вы хотите узнать больше, посетите домашнюю страницу Action:

4. Чтобы опубликовать что-либо на GitHub Pages, программе нужен специальный токен доступа.Причина этого в том, что токен доступа GitHub Action по умолчанию, предоставляемый для всех действий, не имеет доступа к GitHub Pages. Ваш токен доступа должен иметь как минимум привилегий репо . См. Следующий документ:

Запомните токен, потому что вы больше не сможете его увидеть.

5. Чтобы использовать этот токен, вам необходимо сделать его доступным для ваших рабочих процессов. Вы можете сделать это, перейдя в настройки> секреты> новое. Назовите его ACCESS_TOKEN .

6.Затем вы должны создать новую ветку gh-pages . Для этого выберите master ветку и введите gh-pages . Щелкните ссылку Create branch: gh-pages from 'master' link.

GitHub / jazzy теперь запустит ваш рабочий процесс и создаст веб-сайт документации.

Для получения дополнительной информации о действиях GitHub посетите домашнюю страницу действий GitHub:

Как я упоминал ранее, GitHub предлагает разместить вашу документацию бесплатно через страницы GitHub.Настроить это очень просто.

Затем перейдите к https://github.com/<ваше имя пользователя> / / settings . Прокрутите вниз до «Страницы GitHub».

В разделе «Источник» выберите вариант «ветвь gh-pages».

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

Интерактивная ссылка: https://jazzy-github.github.io/my-package/

Поздравления! Теперь ваш проект размещен на GitHub.

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

Testing

Вам также может понравиться этот Action, который автоматически запускает тесты в Ubuntu и / или macOS. Включая тесты для ваших PR!

Стиль

swiftlint (еще один проект Realm) GitHub Действие для обеспечения согласованного стиля кода:

Готово! Теперь у вас есть идеальная установка для тестирования / документации для вашего Swift Package.

Вот несколько полезных ссылок для изучения:

  • Это руководство по созданию API-интерфейсов проектирования в Swift от Джона Санделла:
  • Руководство по стилю Swift от Рэя Вендерлиха:

Документация по Swift · Джесси Сквайрс

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

Успешные проекты с открытым кодом

С открытым исходным кодом, я узнал, что если вы хотите стимулировать внедрение своей библиотеки, вам нужно несколько вещей:

  1. Отличная библиотека, решающая реальную проблему для разработчиков (конечно же!)
  2. Вам необходимо создать открытое и поддерживающее сообщество вокруг вашего проекта
  3. Напишите отличную и легкодоступную документацию.

Если вы посмотрите на любой популярный проект (даже за пределами сообщества Swift / Objective-C / Cocoa), вы найдете эти общие атрибуты.См. Разделы Alamofire, CocoaPods и JSQMessagesViewController.

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

Написание документов

Написание четкой и понятной документации нелегко для изучения и труднее объяснять. Лучший способ научиться писать документацию - это прочитать документацию . Если вы пишете библиотеку для iOS, позвольте документации iOS направлять вас.Если вы пишете библиотеку на Swift, позвольте документации Swift помочь вам. Как эти авторы объясняют определенные концепции или значения параметров? Найдите API-интерфейсы, похожие на те, которые вы написали для своей библиотеки, и начните писать, подражая другим - будь то Apple или других авторов с открытым исходным кодом. Итерируйте, пока не придете к чему-то, что однозначно объясняет ваш API.

Вот пример из JSQMessagesViewController. Это не Swift, но он иллюстрирует эти идеи.

  / **
 * Запрашивает источник данных для данных сообщения, которые соответствуют указанному элементу в indexPath в collectionView.
 *
 * @param collectionView Представление коллекции, запрашивающее эту информацию.
 * @param indexPath Путь к индексу, определяющий расположение элемента.
 *
 * @return Инициализированный объект, соответствующий протоколу `JSQMessageData`. Вы не должны возвращать `nil` из этого метода.
 * /
- (id ) collectionView: (JSQMessagesCollectionView *) collectionView messageDataForItemAtIndexPath: (NSIndexPath *) indexPath;
  

Читается очень похоже на метод UICollectionViewDataSource - collectionView: cellForItemAtIndexPath: .Он следует прецеденту, установленному UIKit, не только с точки зрения дизайна API, но и документации. Благодаря этому ваша библиотека будет казаться пользователям естественной и знакомой.

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

Также стремимся обеспечить 100% покрытие. Сделать это относительно легко.Это намного проще, чем, например, иметь 100% тестовое покрытие. Это то, чем можно гордиться, и это заставит вас и вашу библиотеку почувствовать себя полноценной.

И последний совет - используйте плагин Вэй Ванга, VVDocumenter-Xcode. Этот плагин Xcode сгенерирует для вас шаблоны комментариев документа. Все, что вам нужно сделать, это ввести /// над любым методом или классом, а затем заполнить документы.

Создание документов

Безусловно, лучший способ создавать документы для библиотек Swift (и Objective-C!) - использовать Realm jazzy - Soulful docs для Swift и Objective-C .Это потрясающий проект и один из моих любимых инструментов с открытым исходным кодом, поддерживаемый JP Simard и Samuel Giddins.

После установки просто запустите jazzy из командной строки с несколькими параметрами конфигурации, и вы получите красиво сгенерированные документы за секунды. В README есть все подробности, но вот пример из PresenterKit:

  jazzy --swift-версия 2.2 -o ./ \
      --source-каталог PresenterKit / \
      --readme PresenterKit / README.md \
      -a 'Джесси Сквайрс' \
      -u 'https: // twitter.ru / jesse_squires '\
      -m 'PresenterKit' \
      -g 'https://github.com/jessesquires/PresenterKit'
  

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

Издательская документация

Publishing - последний кусочек этой головоломки. Если вы распространяете свою библиотеку с помощью CocoaPods, вы получите CocoaDocs бесплатно.Спасибо, Орта! Обратите внимание, что CocoaDocs использует jazzy для модулей Swift.

Однако для серверного Swift или проектов, которые не используют CocoaPods, вам понадобится другое решение. Даже Swift Package Manager не предлагает никаких решений для документации. Лучшее решение, которое я нашел для публикации, - это GitHub Pages. Все, что вам нужно сделать, это создать в git ветку-сироту с именем gh-pages , добавить HTML-код или уценку с помощью Jekyll, и ваш сайт будет опубликован по адресу username.github.io/repository .(Фактически, этот сайт размещен на страницах GitHub и создается с помощью Jekyll.) Что мне больше всего нравится в использовании GitHub Pages для документов, так это то, что он хранит все, что содержится в одном репозитории. Таким образом, у вас есть контроль версий не только для вашего исходного кода, но и для вашей документации.

Но если ваш исходный код и документы находятся в отдельных непересекающихся ветвях, то как вы координируете их работу, чтобы поддерживать ваши документы в актуальном состоянии? Об этом мы и поговорим дальше.

Примечание: Несмотря на то, что CocoaDocs предоставляет документы бесплатно, я все же предпочитаю использовать jazzy и страницы GitHub в дополнение к этому.Один небольшой недостаток CocoaDocs - невозможность обновлять документацию независимо от выпуска версии. Предположим, вы выпускаете v1.0 своей библиотеки, а затем обнаруживаете ошибки в своей документации. Чтобы обновить CocoaDocs, вам необходимо отправить другую версию, например v1.0.1 , в CocoaPods. В любом случае хорошо иметь документацию в обоих местах. Независимо от того, обнаруживает ли пользователь вашу библиотеку через GitHub или CocoaPods, документы всегда под рукой.

Полный рабочий процесс

Мы рассмотрели написание, создание и публикацию.Теперь давайте узнаем, как мы можем объединить их в единый, в основном автоматизированный рабочий процесс. Я расскажу, как я настроил это для всех своих библиотек. В качестве примера мы воспользуемся JSQCoreDataKit.

Филиалы
  • Ветка разработки содержит библиотеку, пример приложения, файл readme и другие вспомогательные файлы, такие как .podspec и .travis.yml .
  • Ветка gh-pages содержит только документацию и скрипты для ее создания.
Справочники

На своей машине я проверяю репо дважды .Одна касса для веток develop и gh-pages .

  • ~ / GitHub / JSQCoreDataKit - это касса для разработки
  • ~ / GitHub-Pages / JSQCoreDataKit - это проверка для gh-страниц

Эта установка позволяет мне легче разрабатывать и писать документы, а также быстро создавать и просматривать созданные документы. Постоянное переключение веток вызовет большой отток, поскольку ветка gh-pages не содержит исходный код библиотеки.

Субмодули

Вот где все сходится. В ветку gh-pages я добавляю ветку библиотеки develop как подмодуль git. Запустив обновление подмодуля git , ветка gh-pages может извлекать исходный код библиотеки, не включая его в историю git. Теперь мы можем запустить jazzy из корневого каталога проверки gh-pages и предоставить каталог подмодуля как --source-directory .

Автоматика

В ветке gh-pages пакета JSQCoreDataKit вы найдете два небольших сценария bash.

Первый - build_docs.sh, который обновит подмодуль и построит документы. Затем их можно предварительно просмотреть в Safari, открыв index.html .

  обновление подмодуля git --remote

jazzy --swift-версия 2.2 -o ./ \
      --source-каталог JSQCoreDataKit / \
      --readme JSQCoreDataKit / README.md \
      -a 'Джесси Сквайрс' \
      -u 'https: // twitter.ru / jesse_squires '\
      -m 'JSQCoreDataKit' \
      -g 'https://github.com/jessesquires/JSQCoreDataKit'
  

Второй - publish_docs.sh, который сначала вызовет сценарий сборки, а затем отправит документы на GitHub.

  ./build_docs.sh
git add.
git commit -am "автоматическое обновление документов"
git push
git статус
  
Рабочий процесс

При наличии всего этого обновление документации для моей библиотеки безболезненно. Я пишу код и документацию, а затем нажимаю на , разрабатываю .Затем я переключаю каталоги на gh-pages checkout и запускаю ./publish_docs.sh .

  компакт-диск ~ / GitHub / JSQCoreDataKit
# написать код и документы
# совершить
git push

cd ~ / GitHub-Pages / JSQCoreDataKit
./publish_docs.sh # обновить документы
  

Прямо сейчас я предпочитаю запускать сценарий publish_docs.sh вручную, чтобы документы обновлялись только тогда, когда я хочу - для исправлений и основных выпусков. Однако вы легко можете сделать это на шаге after_success: вашего скрипта Travis-CI.

Вот окончательный продукт для JSQCoreDataKit.

Это просто

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

Опубликовано в категории: Разное

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

Ваш адрес email не будет опубликован. Обязательные поля помечены *