Veel talen ondersteunen documentatieopmerkingenom een ​​generator toe te staan ​​(zoals javadocof doxygen) om codedocumentatie te genereren door diezelfde code te ontleden.

Heeft Swift een dergelijke functie voor opmerkingen over typedocumentatie?

Antwoord 1, autoriteit 100%

Documentatie-opmerkingen worden standaard ondersteund in Xcode, en produceren slim weergegeven documentatie in Quick Help (zowel in de popover wanneer ⌥-op symbolen klikt, als in de Quick Help Inspector ⌥⌘2).

Opmerkingen bij de symbooldocumentatie zijn nu gebaseerd op dezelfde Markdown-syntaxisdie wordt gebruikt door uitgebreide speelplaatsopmerkingen, dus veel wat je kunt doen in speeltuinen kan nu direct worden gebruikt in de broncodedocumentatie.

Voor volledige details van de syntaxis, zie Referentie voor opmaakopmaak. Merk op dat er enkele discrepanties zijn tussen de syntaxis voor rijke speelplaatsopmerkingen & symbool documentatie; deze worden vermeld in het document (blokaanhalingstekens kunnen bijvoorbeeld alleen worden gebruikt in speeltuinen).

Hieronder staat een voorbeeld en een lijst van de syntaxiselementen die momenteel werken voor opmerkingen over symbooldocumentatie.

Updates

Xcode 7 beta 4 ~Toegevoegd "- Throws: ..." als een top-level lijstitem dat naast parameters en retourbeschrijvingen in Quick Help verschijnt.

Xcode 7 beta 1 ~Enkele belangrijke wijzigingen in de syntaxis met Swift 2 - documentatie-opmerkingen nu gebaseerd op Markdown (hetzelfde als playgrounds).

Xcode 6.3 (6D570) ~Ingesprongen tekst wordt nu opgemaakt als codeblokken, waarbij volgende inspringingen worden genest. Het lijkt niet mogelijk om een ​​lege regel in zo'n codeblok te laten - als je dit probeert, wordt de tekst aan het einde van de laatste regel geplakt met tekens erin.

Xcode 6.3 beta ~Inline-code kan nu worden toegevoegd aan documentatie-opmerkingen met behulp van backticks.

Voorbeeld voor 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."
}

Syntax voor Swift 2 (gebaseerd op Markdown)

Commentaarstijl

Zowel ///(inline) als /** */(blok)stijlcommentaren worden ondersteund voor het produceren van documentatiecommentaar. Hoewel ik persoonlijk de voorkeur geef aan de visuele stijl van /** */opmerkingen, kan de automatische inspringing van Xcode de opmaak voor deze opmerkingsstijl tijdens het kopiëren/plakken verpesten, omdat het leidende witruimte verwijdert. Bijvoorbeeld:

/**
See sample usage:
    let x = method(blah)
*/

Bij plakken wordt de inspringing van het codeblok verwijderd en wordt deze niet langer weergegeven als code:

/**
See sample usage:
let x = method(blah)
*/

Om deze reden gebruik ik over het algemeen ///en zal ik het ook gebruiken voor de rest van de voorbeelden in dit antwoord.

Blokelementen

Kop:

/// # My Heading

of

/// My Heading
/// ==========

Subkop:

/// ## My Subheading

of

/// My Subheading
/// -------------

Horizontale regel:

/// ---

Niet-geordende lijsten (met opsommingstekens):

/// - An item
/// - Another item

Je kunt ook +of *gebruiken voor ongeordende lijsten, het moet alleen consistent zijn.

Geordende (genummerde) lijsten:

/// 1. Item 1
/// 2. Item 2
/// 3. Item 3

Codeblokken:

///    for item in array {
///        print(item)
///    }

Een inspringing van minimaal vier spaties is vereist.

Inline-elementen

Nadruk (cursief):

/// Add like *this*, or like _this_.

Sterk (vet):

/// You can **really** make text __strong__.

Houd er rekening mee dat u geen sterretjes (*) en onderstrepingstekens (_) op hetzelfde element kunt combineren.

Inline-code:

/// Call `exampleMethod(_:)` to demonstrate inline code.

Links:

/// [Link Text](https://en.wikipedia.org/wiki/Hyperlink)

Afbeeldingen:

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

De URL kan een web-URL zijn (met behulp van "http://") of een absolute bestandspad-URL (het lijkt erop dat relatieve bestandspaden niet werken).

De URL's voor links en afbeeldingen kunnen ook worden gescheiden van het inline-element om alle URL's op één overzichtelijke plaats te houden:

/// A [link][1] an an ![image][2]
///
/// ...
///
/// [1]: http://www.example.com
/// [2]: http://www.example.com/image.jpg

Zoekwoorden

Naast de Markdown-opmaak herkent Xcode andere markup-trefwoorden die prominent worden weergegeven in Quick Help. Deze opmaaksleutelwoorden hebben meestal de indeling - <keyword>:(de uitzondering is parameter, die ook de parameternaam vóór de dubbele punt bevat), waarbij het sleutelwoord zelf kan zijn geschreven met elke combinatie van hoofdletters/kleine letters.

Trefwoorden symboolsectie

De volgende trefwoorden worden weergegeven als prominente secties in de Help-viewer, onder het gedeelte 'Beschrijving' en boven het gedeelte 'Verklaard in'. Wanneer ze zijn opgenomen, is hun volgorde vast zoals hieronder weergegeven, ook al kun je ze in elke gewenste volgorde in je opmerkingen opnemen.

Bekijk de volledig gedocumenteerde lijst met trefwoorden voor secties en hun beoogde gebruik in de Sectie Symbool Sectie Commando's van de Markup Formatting Reference.

/// - parameters:
///   - <#parameter name#>:
///   - <#parameter name#>:
/// - throws:
/// - returns:

Als alternatief kunt u elke parameter op deze manier schrijven:

/// - parameter <#parameter name#>:

Symbool Beschrijving Veld trefwoorden

De volgende lijst met zoekwoorden wordt weergegeven als vetgedrukte koppenin de hoofdtekst van het gedeelte 'Beschrijving' van de Help-viewer. Ze verschijnen in de volgorde waarin je ze schrijft, net als bij de rest van het gedeelte 'Beschrijving'.

Volledige lijst geparafraseerd uit dit uitstekende blogartikeldoor Erica Sadun. Zie ook de volledig gedocumenteerde lijst met trefwoorden en hun beoogde gebruik in de Sectie Symbool Beschrijving Veldopdrachten van de Markup Formatting Reference.

Toeschrijvingen:

/// - author:
/// - authors:
/// - copyright:
/// - date:

Beschikbaarheid:

/// - since:
/// - version:

Vermaningen:

/// - attention:
/// - important:
/// - note:
/// - remark:
/// - warning:

Ontwikkelingsstatus:

/// - bug:
/// - todo:
/// - experiment:

Implementatiekwaliteiten:

/// - complexity:

Functionele semantiek:

/// - precondition:
/// - postcondition:
/// - requires:
/// - invariant:

Kruisverwijzing:

/// - seealso:

 Documentatie exporteren

HTML-documentatie (ontworpen om Apple's eigen documentatie na te bootsen) kan worden gegenereerd vanuit inline documentatie met behulp van Jazzy, een open-source commando- lijnhulpprogramma.

$ [sudo] gem install jazzy
$ jazzy
Running xcodebuild
Parsing ...
building site
jam out ♪♫ to your fresh new docs in `docs`

Consolevoorbeeld uit dit NSHipster-artikel

Antwoord 2, autoriteit 14%

Hier zijn enkele dingen die werken voor het documenteren van snelle code in Xcode 6. Het is erg buggy en gevoelig voor dubbele punten, maar het is beter dan niets:

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

Het bovenstaande wordt weergegeven in Quick Help zoals u zou verwachten met opgemaakte numerieke lijsten, opsommingstekens, parameter- en retourwaardedocumentatie.

Niets hiervan is gedocumenteerd - dien een radar in om ze verder te helpen.

Antwoord 3, autoriteit 10%

Nieuw in Xcode 8, je kunt een methode als deze selecteren

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

Druk vervolgens op command+ option+ /of kies "Structuur" - "Documentatie toevoegen "uit het menu "Editor" van Xcode, en het zal de volgende sjabloon voor opmerkingen voor u genereren:

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

Antwoord 4, autoriteit 7%

Swift bevat "///" reactieverwerking (hoewel waarschijnlijk nog niet alles).

Schrijf zoiets als:

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

Klik vervolgens op de functienaam en voilà 🙂

Antwoord 5, autoriteit 3%

Ik kan bevestigen dat ShakenManChild mensen een oplossing heeft geboden

Zorg er wel voor dat er een lege regel onder de beschrijving staat!

Antwoord 6, autoriteit 2%

Ja. Basis algemeen (ik heb er fragmenten voor gemaakt met Obj-C-equivalent)

Doelstelling-C:

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

Snel

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

Antwoord 7, autoriteit 2%

Als je alleen Swift gebruikt, is Jazzy het bekijken waard.

https://github.com/realm/jazzy

Antwoord 8

Ik heb iets interessants gevonden, gravend in het Xcode-binaire bestand. Bestanden met de uitgang .swiftdoc.
Het heeft zeker documenten, omdat deze bestanden de documenten voor de Swift UIKit / Foundation API bevatten, helaas lijkt het een eigen bestandsformaat te zijn, voor gebruik in de documentatieviewer in Xcode.

Antwoord 9

In Xcode Editor -> Structuur -> Documentatie toevoegen.

Antwoord 10

Jazzy kan helpen bij het genereren van prachtige documentatie in Apple-stijl.
Hier is een voorbeeld-app met details over het snel gebruiken en configureren.

https://github.com/SumitKr88/SwiftDocumentationUsingJazzy

Antwoord 11

Misschien is het een goed idee om AppleDoc of Apple's eigen HeaderDocdie niet erg wordt herkend.
Ik kan nog steeds enkele HeaderDoc-hints vinden in 10.9 Mavericks-terminal (headerdoc2html)

Ik raad aan om de nieuwste "Wat is er nieuw in te lezen Xcode"* (niet zeker of het nog steeds onder NDA valt)
*De link verwijst naar de Xcode 5.1-versie die ook informatie over HeaderDoc bevat.

Antwoord 12

Vanaf Xcode 5.0 worden gestructureerde opmerkingen van Doxygen en HeaderDoc ondersteund.

Bron