Komentarze do dokumentacji są obsługiwane natywnie w Xcode, tworząc inteligentnie renderowaną dokumentację w Szybkiej pomocy (zarówno w ⌥okienku podręcznym podczas klikania symboli, jak i w Inspektorze szybkiej pomocy ⌥⌘2).
Komentarze do dokumentacji symboli są teraz oparte na tej samej składni Markdown, co w przypadku bogatych komentarzy na placu zabaw, więc wiele z tego, co można zrobić na placach zabaw, można teraz wykorzystać bezpośrednio w dokumentacji kodu źródłowego.
Aby uzyskać szczegółowe informacje na temat składni, zobacz Dokumentacja formatowania znaczników . Zauważ, że istnieją pewne rozbieżności między składnią bogatych komentarzy na temat placu zabaw i dokumentacji symboli; zostały one wskazane w dokumencie (np. cytaty blokowe można stosować tylko na placach zabaw).
Poniżej znajduje się przykład i lista elementów składni, które obecnie działają w przypadku komentarzy do dokumentacji symboli.
Aktualizacje
Xcode 7 beta 4 ~ Dodano „ - Throws: ...” jako element listy najwyższego poziomu, który pojawia się obok parametrów i opisów zwrotów w Szybkiej pomocy.
Xcode 7 beta 1 ~ Kilka istotnych zmian w składni w Swift 2 - komentarze do dokumentacji oparte na Markdown (tak samo jak place zabaw).
Xcode 6.3 (6D570) ~ Wcięty tekst jest teraz formatowany jako bloki kodu, a kolejne wcięcia są zagnieżdżane. Wydaje się, że nie jest możliwe pozostawienie pustej linii w takim bloku kodu - próba zrobienia tego powoduje, że tekst jest sczepiany na końcu ostatniego wiersza z dowolnymi znakami.
Xcode 6.3 beta ~ Kod wbudowany można teraz dodawać do komentarzy do dokumentacji za pomocą odwrotnej strony.
Przykład dla 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."
}
Składnia Swift 2 (na podstawie Markdown )
Styl komentarza
Zarówno ///(inline) i /** */komentarze (blok) style są obsługiwane wytwarzania komentarzy dokumentacji. Chociaż osobiście wolę wizualny styl /** */komentarzy, automatyczne wcięcie Xcode może zepsuć formatowanie tego stylu komentarzy podczas kopiowania / wklejania, ponieważ usuwa wiodące białe znaki. Na przykład:
/**
See sample usage:
let x = method(blah)
*/
Podczas wklejania wcięcie bloku kodu jest usuwane i nie jest już renderowane jako kod:
/**
See sample usage:
let x = method(blah)
*/
Z tego powodu zazwyczaj używam ///i wykorzystam go do reszty przykładów w tej odpowiedzi.
Blokuj elementy
Nagłówek:
/// # My Heading
lub
/// My Heading
/// ==========
Podtytuł:
/// ## My Subheading
lub
/// My Subheading
/// -------------
Linia pozioma:
/// ---
Listy nieuporządkowane (wypunktowane):
/// - An item
/// - Another item
Możesz także użyć +lub w *przypadku nieuporządkowanych list, musi to być po prostu spójne.
Listy uporządkowane (numerowane):
/// 1. Item 1
/// 2. Item 2
/// 3. Item 3
Bloki kodu:
/// for item in array {
/// print(item)
/// }
Wymagane jest wcięcie co najmniej czterech spacji.
Elementy wbudowane
Nacisk (kursywą):
/// Add like *this*, or like _this_.
Mocny (pogrubiony):
/// You can **really** make text __strong__.
Pamiętaj, że nie można mieszać gwiazdek ( *) i znaków podkreślenia ( _) w tym samym elemencie.
Kod wewnętrzny:
/// Call `exampleMethod(_:)` to demonstrate inline code.
Spinki do mankietów:
/// [Link Text](https://en.wikipedia.org/wiki/Hyperlink)
Zdjęcia:
/// 
Adres URL może być adresem URL w sieci (używając „http: //”) lub bezwzględnym adresem URL ścieżki do pliku (nie mogę uzyskać względnych ścieżek do plików).
Adresy URL linków i obrazów można również oddzielić od elementu wbudowanego, aby wszystkie adresy URL znajdowały się w jednym, zarządzalnym miejscu:
/// A [link][1] an an ![image][2]
///
/// ...
///
/// [1]: http://www.example.com
/// [2]: http://www.example.com/image.jpg
Słowa kluczowe
Oprócz formatowania Markdown Xcode rozpoznaje inne słowa kluczowe znaczników, które są widoczne w Szybkiej pomocy. Te słowa kluczowe znaczników najczęściej przyjmują format - <keyword>:(wyjątek to parameter, który obejmuje także nazwę parametru przed dwukropkiem), w którym samo słowo kluczowe można zapisać dowolną kombinacją wielkich / małych liter.
Słowa kluczowe sekcji symboli
Następujące słowa kluczowe są wyświetlane jako widoczne sekcje w przeglądarce pomocy, poniżej sekcji „Opis” i powyżej sekcji „Zadeklarowane w”. Po uwzględnieniu ich kolejność jest ustalona, jak pokazano poniżej, nawet jeśli możesz uwzględnić je w dowolnej kolejności w komentarzach.
Zobacz w pełni udokumentowaną listę słów kluczowych sekcji i ich zamierzone zastosowania w sekcji Polecenia sekcji symboli w Odwołaniu do formatowania znaczników .
/// - parameters:
/// - <#parameter name#>:
/// - <#parameter name#>:
/// - throws:
/// - returns:
Alternatywnie możesz zapisać każdy parametr w ten sposób:
/// - parameter <#parameter name#>:
Symbol Opis Słowa kluczowe w polu
Poniższa lista słów kluczowych jest wyświetlana jako pogrubione nagłówki w treści sekcji „Opis” przeglądarki pomocy. Pojawią się w dowolnej kolejności, w jakiej je napiszesz, podobnie jak w pozostałej części sekcji „Opis”.
Pełna lista parafrazowana z tego doskonałego artykułu na blogu autorstwa Erici Sadun. Zobacz także w pełni udokumentowaną listę słów kluczowych i ich zamierzone zastosowanie w sekcji Polecenia pola opisu symbolu w Odniesieniu do formatowania znaczników .
Atrybucje:
/// - author:
/// - authors:
/// - copyright:
/// - date:
Dostępność:
/// - since:
/// - version:
Upomnienia:
/// - attention:
/// - important:
/// - note:
/// - remark:
/// - warning:
Stan rozwoju:
/// - bug:
/// - todo:
/// - experiment:
Cechy realizacji:
/// - complexity:
Semantyka funkcjonalna:
/// - precondition:
/// - postcondition:
/// - requires:
/// - invariant:
Odsyłacz:
/// - seealso:
Eksportowanie dokumentacji
Dokumentację HTML (zaprojektowaną tak, by naśladować własną dokumentację Apple) można wygenerować z dokumentacji wbudowanej za pomocą narzędzia wiersza polecenia Jazzy .
$ [sudo] gem install jazzy
$ jazzy
Running xcodebuild
Parsing ...
building site
jam out ♪♫ to your fresh new docs in `docs`
Przykład konsoli wzięty z tego artykułu NSHipster
