Técnicas

Documentação

dataforge doc: gerar Markdown a partir dos comentários do código.

Usar#

bash

dataforge doc lib.df                    # imprime no terminal
dataforge doc src/ --out=doc/API.md     # escreve num arquivo

A convenção#

O comentário imediatamente acima de uma declaração é a sua documentação:

geometria.df

// Biblioteca de geometria.
// Funcoes puras para calculos com formas planas.

// Precisao usada em todos os calculos
steady PI := 3.14159265

// Calcula a area de um circulo.
// O raio precisa ser positivo.
action area_circulo(raio: Number) -> Float:
    yield PI * raio ** 2

Os comentários do topo do arquivo viram a descrição do módulo. Linhas com // ou # valem igualmente.

O que é extraído#

Declaração	Vira
`steady`	lista de constantes
`record`	tabela de campos, com tipo e se tem padrão
`enum`	lista de membros
`trait`	lista de assinaturas
`blueprint`	cabeçalho com herança e traits, mais os métodos
`action`	assinatura completa, com tipos e retorno

A saída#

text

# `geometria.df`

Biblioteca de geometria. Funcoes puras para calculos com formas planas.

## Constantes

- **`PI`** — Precisao usada em todos os calculos

## Ações

### `area_circulo`

```dataforge
action area_circulo(raio: Number) -> Float
```

Calcula a area de um circulo.
O raio precisa ser positivo.

Por que escrever os comentários#

Um comentário que descreve o que a ação faz e quais são as pré-condições vira documentação sem trabalho extra. Compare:

dataforge

// soma
action somar(a, b):

// Soma dois valores numericos.
// Textos sao concatenados; tipos incompativeis disparam TypeError.
action somar(a: Number, b: Number) -> Number:

Num projeto#

bash

dataforge doc src/ --out=doc/API.md

Gera um Markdown único para todos os .df da pasta, na ordem alfabética, com um título por arquivo.