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