Wiele języków obsługuje komentarze do dokumentacji, aby umożliwić generatorowi (jak javadoclub doxygen ) wygenerowanie dokumentacji kodu przez parsowanie tego samego kodu.

Czy Swift ma taką funkcję komentowania dokumentacji typu?

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:
///
/// ![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."
}

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:

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

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

Oto kilka rzeczy, które działają w celu dokumentowania szybkiego kodu w Xcode 6. Jest bardzo błędny i wrażliwy na dwukropki, ale jest lepszy niż nic:

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";
    }
}

Powyższe jest renderowane w Szybkiej pomocy, tak jak można się spodziewać po sformatowanych listach numerycznych, punktorach, dokumentacji parametrów i wartości zwracanej.

Nic z tego nie jest udokumentowane - zgłoś radar, aby im pomóc.

Nowość w Xcode 8 , możesz wybrać taką metodę

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

Następnie naciśnij command+ option+/ lub wybierz „Struktura” - „Dodaj dokumentację” z menu „Edytora” Xcode, a wygeneruje dla ciebie następujący szablon komentarzy:

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

Swift zawiera obsługę komentarzy „///” (choć prawdopodobnie jeszcze nie wszystko).

Napisz coś takiego:

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

}

Następnie kliknij opcję func i voilà :)

Mogę potwierdzić, że ShakenManChild dostarczył rozwiązanie peopr

Tylko upewnij się, że masz pusty wiersz pod opisem!

Tak. Podstawowy wspólny (zrobiłem dla niego fragmenty z odpowiednikiem Obj-C)

Cel C:

/**
 @brief <#Short description - what it is doing#>

 @discussion <#Description#>

 @param  <#paramName#> <#Description#>.

 @return <#dataType#> <#Description#>.
 */

Szybki

/**
<#Short inline description - what it is doing#>

<#Description#>

:param:  <#paramName#> <#Description#>.

:returns: <#dataType#> <#Description#>.
*/

Jeśli używasz tylko Swift, warto przyjrzeć się Jazzy.

https://github.com/realm/jazzy

Znalazłem coś interesującego, kopiąc w pliku binarnym Xcode. Pliki z zakończeniem .swiftdoc. Zdecydowanie ma dokumenty, ponieważ pliki te zawierają dokumenty dla interfejsu API Swift UIKit / Foundation API, niestety wydaje się, że jest to zastrzeżony format pliku, do użytku w przeglądarce dokumentacji w Xcode.

W Xcode Editor -> Struktura -> Dodaj dokumentację.

Jazzy może pomóc w wygenerowaniu pięknej dokumentacji w stylu jabłka. Oto przykładowa aplikacja ze szczegółowymi informacjami na temat szybkiego używania i konfiguracji.

https://github.com/SumitKr88/SwiftDocumentationUsingJazzy

Może warto mieć oko na AppleDoc lub własny HeaderDoc firmy Apple, który nie jest bardzo rozpoznawany. Nadal mogę znaleźć wskazówki HeaderDoc w terminalu 10.9 Mavericks (headerdoc2html)

Polecam przeczytać najnowszą wersję „ Co nowego w Xcode ” * (nie jestem pewien, czy nadal jest objęty NDA) * Link wskazuje na wersję Xcode 5.1, która zawiera także informacje o HeaderDoc.

Począwszy od Xcode 5.0 obsługiwane są komentarze strukturalne Doxygen i HeaderDoc.

Źródło