Bibliotecas

Documentar uma biblioteca

dataforge doc, o exemplo que roda — e a única trava que impede a documentação de envelhecer.

Documentação apodrece calada: o código muda, o texto fica, e ninguém descobre até alguém seguir a instrução e falhar. A defesa é uma só — o exemplo tem de rodar.

dataforge

// ~/ Converte reais para centavos, sem passar por float.
// ~/
// ~/   Dinheiro.centavos("19,99")   ->   1999
// ~/
// ~/ Levanta FalhaDeFormato quando o texto nao e um valor.
action centavos(texto):
    limpo := texto.replace(".", "").replace(",", "")
    yield int(limpo)

assert centavos("19,99") is 1999
assert centavos("1.234,50") is 123450

bash

dataforge doc src/ --out=doc/API.md     # o Markdown, a partir dos comentarios
dataforge doc src/ --formato=json       # para gerar um site

A trava: extrair e executar#

É o que este repositório faz com a própria documentação — 67 páginas geradas, e todo bloco marcado como DataForge é extraído e executado antes de a página existir. Nenhuma promessa da documentação sobrevive a uma mudança que a contradiga.

bash

# no CI da sua biblioteca
dataforge check .          # o que nem chega a rodar
dataforge test .           # os testes
python3 scripts/rodar_exemplos_da_doc.py   # cada bloco do README

O README é a primeira página#

Tem de responder	Em quantas linhas
o que esta biblioteca faz	1
como instalar	1 comando
o menor exemplo completo que funciona	até 15 linhas
o que ela não faz	3 a 5 linhas
onde está o resto	1 link

Continue em dataforge doc e Testes de biblioteca.