Documentação

[alexandre-mbm]

• Documento Markdown com o básico
  • Diagrama arquitetural
  • Diagrama de classes reduzido
• Comentários no código Ruby
  • Geração de documentação a partir deles

@OSMBrasil/owners, se alguém quiser ir ajudando com esta issue, pode ir comitando os coletores comentados (para o tópico acima "Comentários no código Ruby"). Pode também ver, para começar, qual gerador de documentação Ruby podemos usar. Mesmo que não tenhamos aqui uma biblioteca de software que necessite desse tipo de "documentação de API", eu quero possibilitar que através deste projeto os interessados aprendam um pouco de Ruby. Essa pode não ser uma linguagem com elogiável desempenho, mas é bem fácil, multiplaforma, e pode ser usada para resolver um série de coisas.

É por essas mesmas motivações que eu desejo o gem (ver issue #4 ).

Quanto ao documento Markdown com o básico, reservo-o para mim, logicamente. Pois está sendo eu a modelar. E também eu quero usar uma das tecnologias abertas de geração de diagramas que já conheço, especificando-os em arquivos de texto.

[alexandre-mbm]

Entre yard — GitHub lsegal/yard — e ruby-doc, escolho o primeiro. Ele tem uma linguagem própria, fazendo a documentação mais concisa e melhor apresentável. Também é customizável.

Inclusive existe auxílio do yard para geração de diagrama de classes.

O comando yard serve disponibiliza serviço em localhost:8808. Serve para a pessoa não se apressar e colocar documentação quebrada no GitHub:

• http://www.rubydoc.info/github/OSMBrasil/OSMBtranstats/master
  • Levar em conta que o serviço quebra links relativos, no Markdown

"Complementos" interessantes: dkubb/yardstick + lsegal/yard-blame

---

Conclusão importante: para o yard funcionar é preciso ter o gem (issue #4).