Поддерживает ли Swift поддержку создания документации?

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

Есть ли у Swift какая-либо функция комментариев к документации по типу?

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

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

Полную информацию о синтаксисе см. В разделе « Обозначение форматирования разметки» . Обратите внимание, что существуют некоторые несоответствия между синтаксисом для богатых комментариев на игровые площадки и символической документацией; они указаны в документе (например, кавычки могут использоваться только на игровых площадках).

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


Обновления

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

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: /// /// ![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), так и /** */ (block) style для создания комментариев к документации. Хотя я лично предпочитаю визуальный стиль /** */ comments, автоматический отступ 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) 

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

 /// ![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 распознает ключевые слова разметки, чтобы отображать заметки в Quick Help. Эти ключевые слова разметки в основном принимают формат - : (исключение – это parameter , который также включает имя параметра перед двоеточием), где само ключевое слово может быть записано с любой комбинацией символов в верхнем и нижнем регистре.

Ключевые слова раздела Symbol

Следующие ключевые слова отображаются в виде заметных разделов в средстве просмотра справки, ниже раздела «Описание» и выше раздела «Объявлено в». При включении их порядок фиксируется, как показано ниже, даже если вы можете включить их в любом порядке, который вам нравится в ваших комментариях.

См. Полностью задокументированный список ключевых слов раздела и их предполагаемое использование в разделе «Команды раздела символов» в «Справочнике по форматированию разметки» .

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

Вот некоторые вещи, которые работают для документирования быстрого кода в Xcode 6. Он очень глючит и чувствителен к двоеточиям, но это лучше, чем ничего:

 class Foo { /// This method does things. /// Here are the steps you should follow to use this method /// /// 1. Prepare your thing /// 2. Tell all your friends about the thing. /// 3. Call this method to do the thing. /// /// Here are some bullet points to remember /// /// * Do it right /// * Do it now /// * Don't run with scissors (unless it's tuesday) /// /// :param: name The name of the thing you want to do /// :returns: a message telling you we did the thing func doThing(name : String) -> String { return "Did the \(name) thing"; } } 

Вышеуказанное отображается в Quick Help, как и ожидалось, с форматированными численными списками, маркерами, документами параметров и возвращаемого значения.

Ничто из этого не задокументировано – подайте Радар, чтобы помочь им.

Новое в Xcode 8 , вы можете выбрать способ, подобный этому

 func foo(bar: Int) -> String { ... } 

Затем нажмите command + option + / или выберите «Структура» – «Добавить документацию» из меню «Редактор» Xcode, и он создаст для вас следующий шаблон комментариев:

 /// <#Description#> /// /// - parameter bar: <#bar description#> /// /// - returns: <#return value description#> 

Swift включает обработку комментариев «///» (хотя, вероятно, еще не все).

Напишите что-то вроде:

 /// Hey! func bof(a: Int) { } 

Затем нажмите кнопку-щелчок по имени func и voilà 🙂

Я могу подтвердить, что ShakenManChild предоставил peopr решение

Просто убедитесь, что у вас есть пустая строка ниже описания!

Недействительная ситуация

Надлежащим образом

Другой путь

Другой стиль комментариев

Если вы используете Swift, то Jazzy стоит посмотреть.

https://github.com/realm/jazzy

Да. Базовая общая (я сделал для нее fragmentы с эквивалентом Obj-C)

Objective-C:

 /** @brief <#Short description - what it is doing#> @discussion <#Description#> @param <#paramName#> <#Description#>. @return <#dataType#> <#Description#>. */ 

стриж

 /** <#Short inline description - what it is doing#> <#Description#> :param: <#paramName#> <#Description#>. :returns: <#dataType#> <#Description#>. */ 

Я нашел что-то интересное, копая в двоичном коде Xcode. Файлы с окончанием .swiftdoc . У него определенно есть документы, потому что эти файлы содержат документы для Swift UIKit / Foundation API, к сожалению, это, по-видимому, проприетарный формат файла, для использования в средстве просмотра документации в Xcode.

В редакторе Xcode -> Структура -> Добавить документацию.

введите описание изображения здесь

Может быть, это хорошая идея – следить за AppleDoc или собственным HeaderDoc от Apple, который не очень признается. Я все еще могу найти подсказки HeaderDoc в терминале 10.9 Mavericks (headerdoc2html)

Я рекомендую прочитать последнюю версию « Что нового в Xcode » * (не уверен, что она все еще находится под NDA). * Ссылка указывает на версию Xcode 5.1, в которой также содержатся сведения о HeaderDoc.

С Xcode 5.0 поддерживаются Docsgen и HeaderDoc структурированные комментарии.

Источник

Давайте будем гением компьютера.