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

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

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

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

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

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

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

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

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

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

В 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

Сравнение 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 серьезных акцента: , `` .

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

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

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

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

Установка

Установка очень проста с менеджером пакетов 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».

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

Поздравления! Теперь ваш проект размещен на 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.

Это просто

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