Зауваження щодо документації підтримуються в 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 (на основі 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)
/// }
Необхідний відступ принаймні чотирьох пробілів.
Вбудовані елементи
Наголос (курсив):
/// 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
