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:
///
/// 
///
/// - 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:
/// 
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
