Комментарии к документации изначально поддерживаются в XCode, создавая грамотно оформленную документацию в быстрой справке (как в всплывающем окне при ⌥нажатии символов, так и в инспекторе быстрой справки ⌥⌘2).
Комментарии к символьной документации теперь основаны на том же синтаксисе Markdown, который используется в богатых комментариях к игровым площадкам, поэтому многое из того, что вы можете делать на игровых площадках, теперь можно использовать непосредственно в документации по исходному коду.
Для получения полной информации о синтаксисе см. Справочник по форматированию разметки . Обратите внимание, что есть некоторые несоответствия между синтаксисом для богатых комментариев к игровой площадке и документации символов; они указаны в документе (например, кавычки могут использоваться только на игровых площадках).
Ниже приведен пример и список элементов синтаксиса, которые в настоящее время работают для комментариев документации по символам.
Обновления
Xcode 7 beta 4 ~ Добавлено " - Throws: ..." как элемент списка верхнего уровня, который отображается рядом с параметрами и возвращает описания в быстрой справке.
Xcode 7 beta 1 ~ Некоторые существенные изменения в синтаксисе со Swift 2 - комментарии к документации теперь основаны на Markdown (аналогично игровым площадкам).
Xcode 6.3 (6D570) ~ Текст с отступом теперь отформатирован как блоки кода с последующими вложенными отступами. Кажется невозможным оставить пустую строку в таком блоке кода - попытка сделать это приводит к тому, что текст будет добавлен в конец последней строки с любыми символами в нем.
Xcode 6.3 beta ~ Встроенный код теперь может быть добавлен в комментарии к документации с помощью обратных галочек.
Пример для Swift 2
/// Text like this appears in "Description".
///
/// Leave a blank line to separate further text into paragraphs.
///
/// You can use bulleted lists (use `-`, `+` or `*`):
///
/// - Text can be _emphasised_
/// - Or **strong**
///
/// Or numbered lists:
///
/// 7. The numbers you use make no difference
/// 0. The list will still be ordered, starting from 1
/// 5. But be sensible and just use 1, 2, 3 etc…
///
/// ---
///
/// More Stuff
/// ==========
///
/// Code
/// ----
///
/// Use backticks for inline `code()`. Indentations of 4 spaces or more will create a code block, handy for example usage:
///
/// // Create an integer, and do nothing with it
/// let myInt = 42
/// doNothing(myInt)
///
/// // Also notice that code blocks scroll horizontally instead of wrapping.
///
/// Links & Images
/// --------------
///
/// Include [links](https://en.wikipedia.org/wiki/Hyperlink), and even images:
///
/// 
///
/// - note: That "Note:" is written in bold.
/// - requires: A basic understanding of Markdown.
/// - seealso: `Error`, for a description of the errors that can be thrown.
///
/// - parameters:
/// - int: A pointless `Int` parameter.
/// - bool: This `Bool` isn't used, but its default value is `false` anyway…
/// - throws: A `BadLuck` error, if you're unlucky.
/// - returns: Nothing useful.
func doNothing(int: Int, bool: Bool = false) throws -> String {
if unlucky { throw Error.BadLuck }
return "Totally contrived."
}
Синтаксис для Swift 2 (на основе уценки )
Стиль комментариев
Оба ///(встроенный) и /** */(блочный) стиль комментариев поддерживаются для создания комментариев документации. Хотя я лично предпочитаю визуальный стиль /** */комментариев, автоматическое отступление XCode может испортить форматирование для этого стиля комментариев при копировании / вставке, поскольку оно удаляет начальные пробелы. Например:
/**
See sample usage:
let x = method(blah)
*/
При вставке отступ блока кода удаляется и больше не отображается как код:
/**
See sample usage:
let x = method(blah)
*/
По этой причине я обычно использую ///и буду использовать это для остальных примеров в этом ответе.
Блочные элементы
Заголовок:
/// # My Heading
или
/// My Heading
/// ==========
Подрубрика:
/// ## My Subheading
или
/// My Subheading
/// -------------
Горизонтальное правило:
/// ---
Неупорядоченные (маркированные) списки:
/// - An item
/// - Another item
Вы также можете использовать +или *для неупорядоченных списков, это просто должно быть последовательным.
Упорядоченные (пронумерованные) списки:
/// 1. Item 1
/// 2. Item 2
/// 3. Item 3
Блоки кода:
/// for item in array {
/// print(item)
/// }
Требуется отступ не менее четырех пробелов.
Встроенные элементы
Акцент (курсив):
/// Add like *this*, or like _this_.
Сильный (жирный):
/// You can **really** make text __strong__.
Обратите внимание, что вы не можете смешивать звездочки ( *) и подчеркивание ( _) в одном элементе.
Встроенный код:
/// Call `exampleMethod(_:)` to demonstrate inline code.
Ссылки:
/// [Link Text](https://en.wikipedia.org/wiki/Hyperlink)
Изображений:
/// 
URL-адрес может быть либо веб-URL-адресом (с использованием «http: //»), либо URL-адресом абсолютного пути к файлу (кажется, я не могу заставить работать относительные пути к файлам).
URL-адреса для ссылок и изображений также можно отделить от встроенного элемента, чтобы сохранить все URL-адреса в одном управляемом месте:
/// A [link][1] an an ![image][2]
///
/// ...
///
/// [1]: http://www.example.com
/// [2]: http://www.example.com/image.jpg
Ключевые слова
В дополнение к форматированию Markdown, XCode распознает другие ключевые слова разметки, которые отображаются на видном месте в быстрой справке. Эти ключевые слова разметки в основном принимают формат - <keyword>:(за исключением того parameter, что также включает имя параметра перед двоеточием), где само ключевое слово может быть написано с любой комбинацией символов верхнего и нижнего регистра.
Ключевые слова раздела символов
Следующие ключевые слова отображаются в виде заметных разделов в средстве просмотра справки, под разделом «Описание» и над разделом «Объявлено». Когда они включены, их порядок фиксируется, как показано ниже, даже если вы можете включить их в любом порядке, который вам нравится в ваших комментариях.
См. Полностью документированный список ключевых слов раздела и их предполагаемое использование в разделе «Команды раздела символов» справочника по форматированию разметки .
/// - parameters:
/// - <#parameter name#>:
/// - <#parameter name#>:
/// - throws:
/// - returns:
Кроме того, вы можете написать каждый параметр следующим образом:
/// - parameter <#parameter name#>:
Символ Описание Ключевые слова поля
Следующий список ключевых слов отображается в виде жирных заголовков в теле раздела «Описание» средства просмотра справки. Они будут отображаться в любом порядке, в котором вы их пишете, как и в остальной части раздела «Описание».
Полный список перефразирован из этой замечательной статьи Эрики Садун. Также см. Полностью документированный список ключевых слов и их предполагаемое использование в разделе «Команды поля описания символа» в справочнике по форматированию разметки .
атрибуции:
/// - author:
/// - authors:
/// - copyright:
/// - date:
Доступность:
/// - since:
/// - version:
Наставления:
/// - attention:
/// - important:
/// - note:
/// - remark:
/// - warning:
Состояние развития:
/// - bug:
/// - todo:
/// - experiment:
Качество реализации:
/// - complexity:
Функциональная семантика:
/// - precondition:
/// - postcondition:
/// - requires:
/// - invariant:
Перекрестная ссылка:
/// - seealso:
Экспорт документации
HTML-документация (предназначенная для имитации собственной документации Apple) может быть сгенерирована из встроенной документации с использованием утилиты командной строки с открытым исходным кодом Jazzy .
$ [sudo] gem install jazzy
$ jazzy
Running xcodebuild
Parsing ...
building site
jam out ♪♫ to your fresh new docs in `docs`
Пример консоли, взятый из этой статьи NSHipster
