комментарии к документации поддерживаются изначально в Xcode, создавая умно визуализированную документацию в быстрой справке (как в popover, когда ⌥ - щелчок по символам, а в быстрой справке инспектор ⌥⌘2).

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

для получения полной информации о синтаксисе см. Ссылка На Форматирование Разметки. Обратите внимание, что есть некоторые расхождения между синтаксисом для rich playground comments & symbol documentation; они указаны в документе (например, блочные кавычки могут использоваться только в игровых площадках).

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

---

обновления

Xcode 7 beta 4 ~ добавил:"- Throws: ... " как элемент списка верхнего уровня, который отображается вместе с параметрами и возвращаемыми описаниями в быстрой справке.

Xcode 7 beta 1 ~ некоторые существенные изменения в синтаксисе с комментариями Swift 2-documentation теперь основаны на 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:
///
/// ![Swift Logo](/Users/Stuart/Downloads/swift.png "The logo for the Swift programming language")
///
/// - 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 (на основе Markdown)

Стиль Комментария

и /// (inline) и /** */ (блок) комментарии стиля поддерживаются для создания комментариев документации. Хотя лично я предпочитаю визуальный стиль /** */ комментарии, автоматический отступ 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)
///    }

требуется отступ не менее четырех пробелов.

Inline Элементы

акцент (курсивом):

/// Add like *this*, or like _this_.

сильный (смелый):

/// You can **really** make text __strong__.

обратите внимание, что вы не можете смешивать звездочки (*) и подчеркивания (_) на том же элементе.

HTML-код:

/// Call `exampleMethod(_:)` to demonstrate inline code.

ссылки:

/// [Link Text](https://en.wikipedia.org/wiki/Hyperlink)

изображение:

/// ![Alt Text](http://www.example.com/alt-image.jpg)

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