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

Комментарии к документации символов теперь основаны на том же синтаксисе разметки, который используется комментариями rich playground, поэтому многое из того, что вы можете сделать в playgrounds, теперь можно использовать непосредственно в документации исходного кода.

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

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

---

Обновления

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 )

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

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

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

Встроенные Элементы

Курсив (курсивом)):

/// 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)

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

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

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