Carregando...

Swift - Gerando Doc com jazzy

27 de outubro de 2017

 

Olá pessoal. Hoje vou explicar de uma maneira bem simples como podemos gerar uma documentação de nosso aplicativo de uma forma bem rápida e sem dor de cabeçar. Usando o Jazzy

 

 

Jazzy

O Jazzy é uma ferramenta de linha de comando que gera a documentação de nosso projeto baseada na documentação de cada código fonte, classe, função , struct ...

Ele suporta alguns bons tipos de formato de marcação abaixo alguns links.

A lista completa e documentação pode ser encontradas no pŕoprio git do Jazzy

Bom vamos por a mão na massa.
 

MacOS

Instalação

Precisamos ter instaladao o Ruby em nossa maquina. portanto abra o terminal e digite:  ruby --version

Caso não tenha instalado recomendo o RVM ou instele via Brew.

Feito?

Certo seguimos então com o seguinte comando:

sudo gem install jazzy

Aguarde o final da instalação e pronto já podemos usar. O Jazzy tem seu próprio help parão digitando o jazzy -h

 

Um exemplo basico de documentação.

/**

         Documentação para func com param

     

     - Parameter login: ***String*** com login

     

     - SeeAlso: `Usuario`

     */

    func testeDoc(login: String){

 

.   ...

    }

 

Para excluir da documentação use uma declaração de comentário para documentação com  :nodoc:

/**

 :nodoc:

 */

class AppDelegate: UIResponder, UIApplicationDelegate {

....

 }

 

 

Gerando a documentação

 

Feito isso você precisa voltar para o terminal entre na pasta raiz do projeto e execute o comando:  jazzy --min-acl internal

Vocë deve ter a seguinte saída

 

 

porque --min-acl internal ?

Você poderia apenas executar jazzy  Mas a  documentação deixa claro que por padrão ele procura por padrão declarações publicas e abertas.

Como nosso código é bem padrão precisamos setar o internal como parametro de requisito minimo de geração.

 

Acessando a documentação

 

Entre na pasta do projeto e procurar por outra chamada docs. Dentro dela existe um arquivo index.html dois clicks neste arquivo e a documentação é aberta no navegador padrão de sua maquina.

 

 

- Note que nesta imagem acima a classe AppDelegate ainda aparece. Se você baixar o reposiório do post verá que a documentação com :nodoc: foi adicionada e ela foi removida da documentação final.

 

Deixei todo o fonte e doc em meu git para darem uma olhada segue o link Git postjazzy

 

Linux

Em breve ... estou montando certinho o passo a passo. pois é um pouco diferente na parte de dependências.

 

 

 

Simples não?

 

Como eu gosto de dizer. Uma boa documentação vale por mil palavras.

 

 

Desenvolvido por Masters Mx