O Swift tem suporte para geração de documentação?


238

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?


Sabendo que Xcode com Objective-C permite comentários de documentação, acredito que a Apple irá adicionar esta opção para Xcode com rápida no futuro próximo (no entanto, é apenas uma suposição, não tenho provas)
Garoal

@ Δdeveloper Supunha o mesmo, mas como não vi nenhuma referência, fiquei imaginando se alguém pode confirmá-la e também se haverá alguma ferramenta de documentação específica.
pconcepcion

1
Eles definitivamente adicionarão algo no futuro, o // MARK:comentário também está agendado para uma versão futura do Xcode.
Leandros

Os comentários no estilo Doxygen funcionam como métodos de classe, com ~ várias ~ MUITAS advertências. Eu, por exemplo, continuarei usando o estilo Doxygen (como fiz para Obj-C) e espero que o Xcode melhore seu suporte a eles.
187 Pascal

1
Para documentar os parâmetros do bloco, consulte stackoverflow.com/a/41970146/1054573
Leonard Pauli

Respostas:


386

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

Ajuda rápida da documentação rápida


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


1
Parece que o comportamento mudou na versão final do Xcode 6.3 (6D570). Os blocos recuados agora estão formatados como blocos de código e podem ser aninhados com mais de dois níveis.
NexD.

2
Descrição muito boa da sintaxe da documentação do Swift 2.0. Você deve atualizar a publicação para incluir o/// - todo: keyword
Leonardo

2
@uchuugaka Na verdade não. Pode ter sido baseado no reStructuredText anteriormente, mas, a partir do Xcode 7, os comentários da documentação são baseados no Markdown, com o mesmo formato básico dos comentários do playground. Consulte as Notas de versão do Xcode 7 para obter detalhes.
Stuart

2
Existe uma maneira de vincular a outras funções no mesmo arquivo, como o JavaDoc? Por exemplo, "ver myOtherMethod(param1:)para funcionalidade estendida"
Ben leggiero

1
@BenLeggiero, sim, usando /// - Tag: otherMethode [otherMethod](x-source-tag://otherMethod). Para mais detalhes, veja minha resposta .
Clay Ellis

58

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.


2
Mattt Thompson escreveu um artigo sobre isso , e ele pensa que é reStructuredText.
Eonil

No exemplo acima, os símbolos de mais (+) e menos (-) também atuam como pontos de bala, além dos asteriscos mostrados.
Vince O'Sullivan

Parece que ///é necessária uma linha de comentário ( ) em branco entre qualquer texto explicativo e as linhas :param:ou :returns:. A omissão disso faz com que o XCode (6.1.1 no momento da escrita) inclua a ajuda do parâmetro no corpo principal da descrição da função.
Robin Macharg 11/03/2015

Infelizmente isso não funciona com o Xcode 7 Beta. Espero que eles consertem isso em uma versão de lançamento.
stevo.mit

1
O Xcode 7 adotou uma sintaxe diferente: ericasadun.com/2015/06/14/swift-header-documentation-in-xcode-7
Zmey

41

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#>

Obrigado por isso. Mencionarei apenas que o atalho de teclado que você indica não parece funcionar em um teclado dinamarquês, onde "/" é shift- "7".
RenniePet

27

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à :)


11

Posso confirmar que ShakenManChild forneceu uma solução peopr

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

Uma situação inválida

A maneira certa

Outra maneira

Outro estilo de comentário


8

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#>.
*/


6

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.




-1

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.


-1

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

Fonte


1
Bem, eu estava perguntando sobre Swift neste caso.
Pconcepcion

@pconcepcion Você está usando o Swift no Xcode? Então sim.
22815 Matt Zanchelli

1
Matt, pelo que sei (posso estar errado) Swift não é suportado até o Xcode 6 beta, por isso não tenho certeza se a documentação para o Xcode 5 é válida para o Xcode 6 (e para o Swift)
pconcepcion

@pconcepcion Funciona. Eu tenho usado o mesmo estilo documentação doxygen como eu fiz no Objective-C e funciona. Acima de um método ou propriedade, uso /// This is what the method does.etc.
Matt Zanchelli

Ok, então a coisa é que você tenha testado no Xcode 6. Eu estava confuso, porque você estava falando sobre Xcode 5 e a ligação é para Xcode 5
pconcepcion
Ao utilizar nosso site, você reconhece que leu e compreendeu nossa Política de Cookies e nossa Política de Privacidade.
Licensed under cc by-sa 3.0 with attribution required.