Muitos idiomas suportam comentários de documentação para permitir que um gerador (como javadocou doxygen ) gere documentação de código analisando o mesmo código.

O Swift tem algum recurso de comentário de documentação do tipo como este?

Os comentários da documentação são suportados nativamente no Xcode, produzindo documentação renderizada com inteligência na Ajuda Rápida (tanto nos ⌥símbolos popover quando cliques, quanto no Inspetor de Ajuda Rápida⌥⌘2 ).

Agora, os comentários da documentação do símbolo são baseados na mesma sintaxe Markdown usada pelos comentários avançados do playground, portanto, muito do que você pode fazer nos playgrounds agora pode ser usado diretamente na documentação do código-fonte.

Para obter detalhes completos da sintaxe, consulte Referência de formatação de marcação . Observe que existem algumas discrepâncias entre a sintaxe para comentários ricos sobre o playground e documentação de símbolos; estes são apontados no documento (por exemplo, citações em bloco só podem ser usadas em playgrounds).

Abaixo está um exemplo e uma lista dos elementos de sintaxe que atualmente funcionam para comentários da documentação de símbolos.

Atualizações

Xcode 7 beta 4 ~ Adicionado " - Throws: ..." como um item de lista de nível superior que aparece ao lado de parâmetros e retorna descrições na Ajuda Rápida.

Xcode 7 beta 1 ~ Algumas mudanças significativas na sintaxe do Swift 2 - comentários de documentação agora baseados no Markdown (o mesmo que playgrounds).

Xcode 6.3 (6D570) ~ O texto recuado agora está formatado como bloco de código, com os recuos subsequentes sendo aninhados. Parece não ser possível deixar uma linha em branco nesse bloco de código - tentar fazer isso resulta no texto sendo pregado no final da última linha com qualquer caractere.

Xcode 6.3 beta ~ O código embutido agora pode ser adicionado aos comentários da documentação usando backticks.

Exemplo para 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."
}

Sintaxe para Swift 2 (com base no Markdown )

Estilo do comentário

Os comentários no estilo ///(em linha) e /** */(em bloco) são suportados para produzir comentários na documentação. Embora eu pessoalmente prefira o estilo visual dos /** */comentários, o recuo automático do Xcode pode arruinar a formatação desse estilo de comentário ao copiar / colar, pois remove os espaços em branco à esquerda. Por exemplo:

/**
See sample usage:

    let x = method(blah)
*/

Ao colar, o recuo do bloco de código é removido e não é mais renderizado como código:

/**
See sample usage:

let x = method(blah)
*/

Por esse motivo, geralmente uso ///e o utilizarei para o restante dos exemplos nesta resposta.

Elementos do bloco

Título:

/// # My Heading

ou

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

Subtítulo:

/// ## My Subheading

ou

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

Regra horizontal:

/// ---

Listas não ordenadas (com marcadores):

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

Você também pode usar + ou *para listas não ordenadas, apenas precisa ser consistente.

Listas ordenadas (numeradas):

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

Blocos de código:

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

É necessário um recuo de pelo menos quatro espaços.

Elementos em linha

Ênfase (itálico):

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

Forte (negrito):

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

Observe que você não pode misturar asteriscos ( *) e sublinhados ( _) no mesmo elemento.

Código embutido:

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

Ligações:

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

Imagens:

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

O URL pode ser um URL da Web (usando "http: //") ou um URL absoluto do caminho do arquivo (parece que não consigo fazer com que os caminhos relativos do arquivo funcionem).

Os URLs para links e imagens também podem ser separados do elemento inline para manter todos os URLs em um único local gerenciável:

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

Palavras-chave

Além da formatação Markdown, o Xcode reconhece outras palavras-chave de marcação para serem exibidas com destaque na Ajuda Rápida. Essas palavras-chave de marcação geralmente assumem o formato - <keyword>:(a exceção éparameter , que também inclui o nome do parâmetro antes dos dois pontos), onde a própria palavra-chave pode ser escrita com qualquer combinação de caracteres maiúsculos / minúsculos.

Palavras-chave da seção Símbolo

As seguintes palavras-chave são exibidas como seções destacadas no visualizador de ajuda, abaixo da seção "Descrição" e acima da seção "Declarado em". Quando incluídas, a ordem delas é fixada conforme exibido abaixo, mesmo que você possa incluí-las na ordem que desejar nos seus comentários.

Consulte a lista totalmente documentada de palavras-chave da seção e seus usos pretendidos na seção Comandos da seção de símbolos da Referência de formatação de marcação .

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

Como alternativa, você pode escrever cada parâmetro desta maneira:

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

Símbolo Descrição Palavras-chave do campo

A lista de palavras-chave a seguir é exibida como títulos em negrito no corpo da seção "Descrição" do visualizador de ajuda. Eles aparecerão na ordem em que você os escrever, como no restante da seção "Descrição".

Lista completa parafraseada deste excelente artigo de blog de Erica Sadun. Consulte também a lista totalmente documentada de palavras-chave e seus usos pretendidos na seção Comandos do campo Descrição do símbolo da Referência de formatação de marcação .

Atribuições:

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

Disponibilidade:

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

Advertências:

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

Estado de desenvolvimento:

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

Qualidades de implementação:

/// - complexity:

Semântica Funcional:

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

Referência cruzada:

/// - seealso:

 Exportando documentação

A documentação HTML (projetada para imitar a documentação da Apple) pode ser gerada a partir da documentação embutida usando o Jazzy , um utilitário de linha de comando de código aberto.

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

Exemplo de console extraído deste artigo do NSHipster

Aqui estão algumas coisas que funcionam para documentar códigos rápidos no Xcode 6. É muito problemático e sensível a dois pontos, mas é melhor que nada:

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

O acima é renderizado na Ajuda Rápida, como seria de esperar com listas numéricas formatadas, marcadores, parâmetros e documentação de valor de retorno.

Nada disso está documentado - envie um radar para ajudá-los.

Novo no Xcode 8 , você pode selecionar um método como este

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

Em seguida, pressione command+ option+/ ou escolha "Estrutura" - "Adicionar documentação" no menu "Editor" do Xcode, e ele gerará o seguinte modelo de comentários para você:

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

Swift inclui manipulação de comentários "///" (embora provavelmente nem tudo ainda).

Escreva algo como:

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

}

Em seguida, clique no nome do func e voilà :)

Posso confirmar que ShakenManChild forneceu uma solução peopr

Apenas verifique se você tem uma linha vazia abaixo da descrição!

Sim. Base comum (criei trechos para ele com o equivalente a Obj-C)

Objetivo-C:

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

 @discussion <#Description#>

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

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

Rápido

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

<#Description#>

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

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

Se você estiver usando apenas o Swift, vale a pena olhar para o Jazzy.

https://github.com/realm/jazzy

Eu encontrei algo interessante, cavando no binário do Xcode. Arquivos com o final .swiftdoc. Definitivamente, possui documentos, porque esses arquivos contêm os documentos da API Swift UIKit / Foundation, infelizmente, parece ser um formato de arquivo proprietário, para uso no visualizador de documentação no Xcode.

No Xcode Editor -> Estrutura -> Adicionar documentação.

O Jazzy pode ajudar a gerar uma documentação bonita com estilo da maçã. Aqui está um aplicativo de exemplo com detalhes sobre como usar e configurar rapidamente.

https://github.com/SumitKr88/SwiftDocumentationUsingJazzy

Talvez seja uma boa ideia ficar de olho no AppleDoc ou no próprio HeaderDoc da Apple, que não é muito reconhecido. Ainda encontro algumas dicas do HeaderDoc no terminal Mavericks 10.9 (headerdoc2html)

Eu recomendo ler o mais recente " O que há de novo no Xcode " * (não tenho certeza se ainda está sob o NDA) * O link aponta para a versão do Xcode 5.1 que contém informações sobre o HeaderDoc também.

A partir do Xcode 5.0, os comentários estruturados Doxygen e HeaderDoc são suportados.

Fonte