Многие языки поддерживают комментарии к документации, чтобы позволить генератору (например, javadoc или doxygen) генерировать документацию кода путем анализа тот же код.
Есть ли у Swift какие-либо комментарии к документации по документации или инструменты для создания документации?
Комментарии к документации поддерживаются изначально в Xcode, создавая документацию в виде быстрой визуализации в Quick Help (как в popover, когда ⌥ -clicking символы, так и в 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 ~ Встроенный код теперь можно добавить к комментариям документации с использованием обратных ссылок.
/// 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."
}
Для комментариев документации поддерживаются теги /// (inline) и /** */ (block) style. Хотя я лично предпочитаю визуальный стиль комментариев /** */, автоматический отступ 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 распознает другие ключевые слова разметки, чтобы они отображались в Quick Help. Эти ключевые слова разметки в основном принимают формат - <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
Вот некоторые вещи, которые работают для документирования быстрого кода в 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 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, как и ожидалось, с форматированными числовыми списками, маркерами, документами параметров и возвращаемого значения.
Ничто из этого не документировано - создайте Радар, чтобы помочь им.
Swift включает обработку комментариев "///" (хотя, вероятно, еще не все).
Напишите что-то вроде:
/// Hey!
func bof(a: Int) {
}
Затем нажмите на имя func и нажмите кнопку:)
Новое в Xcode 8, вы можете выбрать способ, подобный этому
func foo(bar: Int) -> String { ... }
Затем нажмите command + option + / или выберите "Структура" - "Добавить документацию" из меню "Редактор" Xcode, и это будет создайте для себя следующий шаблон комментариев:
/// <#Description#>
///
/// - parameter bar: <#bar description#>
///
/// - returns: <#return value description#>
Я могу подтвердить, что ShakenManChild предоставил peopr-решение
Просто убедитесь, что у вас есть пустая строка под описанием!
Если вы используете Swift, тогда Jazzy стоит посмотреть.
Да. Общая база (я сделал для нее фрагменты с эквивалентом Obj-C)
Objective-C:
/**
@brief <#Short description - what it is doing#>
@discussion <#Description#>
@param <#paramName#> <#Description#>.
@return <#dataType#> <#Description#>.
*/
Swift
/**
<#Short inline description - what it is doing#>
<#Description#>
:param: <#paramName#> <#Description#>.
:returns: <#dataType#> <#Description#>.
*/
Я нашел что-то интересное, копая в двоичном коде Xcode. Файлы с окончанием .swiftdoc.
У него определенно есть документы, потому что эти файлы содержат документы для Swift UIKit/Foundation API, к сожалению, это, по-видимому, проприетарный формат файла для использования в средстве просмотра документации в Xcode.
Вы можете сделать Грамотное программирование в Swift с Docco.
В редакторе Xcode → Структура → Добавить документацию.
Может быть, неплохо бы присмотреться к AppleDoc или Apple, HeaderDoc, который не очень признан. Я все еще могу найти подсказки HeaderDoc в терминале 10.9 Mavericks (headerdoc2html)
Я рекомендую прочитать последнюю версию What New In Xcode" * (не уверен, что она все еще находится под NDA) * Ссылка указывает на версию Xcode 5.1, в которой также содержатся сведения о HeaderDoc.
Как и в Xcode 5.0, поддерживаются Docsgen и HeaderDoc структурированные комментарии.