Pular para o conteúdo principal

Como ler a referência e as evidências

Uma página por contrato, apelidos reunidos​

SE e BG_SE aparecem juntos porque um é alias textual do outro. A página reúne os usos dos dois nomes, mostra a definição canônica e a cadeia de expansão. O mesmo vale para os demais nomes curtos. Quando uma macro encaminha para uma função bg_*, a página mostra a relação e o contrato da função.

Anatomia de uma página de símbolo​

SeçãoO que respondeComo foi produzida
Tipo e módulomacro ou função, com ou sem argumentos, categoriaextração do fonte
Assinatura e expansãocomo se escreve e para que expandecorpo literal da macro ou protótipo
Como funcionacontrato e mecânicacontratos.json, comentário ou corpo
Exemplo de usochamada verossímilcontrato editorial, quando existe
Implementaçãocódigo realcorpo extraído com linhas
Como este símbolo aparece nos testesonde e como é usadovarredura de referências com linha
Evidência indiretaquem chamagrafo de chamadas do fonte
Compiladores, padrão C e SOguards e ressalvasdiretivas preservadas
Checklist de integraçãoo que fazer para usarderivado do tipo e do módulo
Perguntas frequentesdúvidas típicas daquele nomedados da própria página

Nem toda seção aparece em toda página: um símbolo sem #if não tem ramo condicional, e um símbolo sem chamada em teste não tem evidência direta.

Tipos de evidência​

EvidênciaO que significaO que não significa
Referência diretaO identificador aparece no código de teste ou na tabela de expansõesQue todos os ramos foram executados
Uso via apelidoO teste usa um nome que expande para a macro documentadaQue o nome prefixado foi escrito literalmente naquele teste
Modo de integraçãoO runner passa um modo ao binário e confere status/diagnósticoQue o teste unitário comum cobriu o mesmo caminho
Evidência indiretaUm chamador do símbolo aparece nos testesQue a função interna foi instrumentada ou medida
Ramo condicionalExiste #if/#ifdef/#else no fonteQue o ramo foi compilado em todos os alvos
Matriz históricaRegistro de execução/compilação/avaliação da fase documentadaResultado automático do build atual deste site

Exemplo de leitura​

Suponha uma página que mostra 18 ocorrências de bg_copia_texto em 4 arquivos. Isso significa que o identificador aparece 18 vezes nesses arquivos — não que a função foi chamada 18 vezes em execução, nem que todas as combinações de capacidade foram testadas.

# conferir manualmente uma referência citada pela página
grep -n "bg_copia_texto" tests/test_biblioteca.c
sed -n '1,20p' tests/test_biblioteca.c

O link de linha leva ao commit do build, então o trecho continua correspondendo ao código que gerou a página.

Contagens​

As contagens do site são estáticas: símbolos definidos, casos em disco, ocorrências e modos localizados. O total impresso por make test é dinâmico e inclui verificações repetidas, sanitizers, ferramentas disponíveis e caminhos realmente executados. Não compare os dois números como se fossem a mesma métrica.

MétricaOnde apareceNatureza
símbolos inventariadosReferênciaestática
casos em discoTestesestática
ocorrências de um nomepágina do símboloestática
verificações aprovadassaída de make testdinâmica
verificações de portabilidadesaída de make test-portabilidadedinâmica

Lacunas são visíveis​

O JSON de cobertura lista símbolos sem referência direta e contratos sem resumo editorial. Uma guarda de inclusão pode legitimamente não ter teste direto; uma função exercitada apenas por um chamador precisa de evidência indireta. O gerador não transforma ausência em aprovação.

python3 - <<'PY'
import json
d = json.load(open("website/static/api/cobertura.json"))
print(len(d["sem_referencia_direta"]), "símbolos sem referência direta")
print(d["sem_referencia_direta"][:10])
PY

Os links de fonte usam o commit do build quando disponível. Assim, a linha mostrada continua correspondendo ao código que gerou aquela página. Em uma árvore local ainda não commitada, o permalink usa o HEAD atual como referência; o build de CI usa o SHA do evento.

DOCS_COMMIT=HEAD python3 tools/gerar_documentacao.py --output /tmp/site

Erros de interpretação comuns​

LeituraProblemaLeitura correta
“A página não tem teste, então não funciona”ausência de referência direta não é ausência de implementaçãoverifique chamadores e cobertura
“70 verificações de portabilidade = 70 alvos”o número conta verificações, não plataformasleia a matriz por alvo
“A macro é a função”macro é substituição de tokens; a função é código compiladoveja se existe bg_* associado
“O exemplo é um teste”exemplo editorial não é executado por si sóprocure o caso dourado correspondente
“O total do site mudou, a suíte regrediu”métricas diferentescompare logs de make test com logs

Perguntas frequentes​

O que significa “Nenhuma referência direta localizada”?​

Que a busca estática não encontrou aquele identificador nos arquivos de teste. Isso é comum em guardas de inclusão, macros de configuração e funções alcançadas apenas por chamadores. A página ainda mostra a definição e o contrato; a lacuna fica registrada no JSON de cobertura.

grep -R "MEU_SIMBOLO" tests/ docs/exemplos/ || echo "sem mencao direta"

Uma ocorrência no código de teste prova que o comportamento foi verificado?​

Não. Prova que o nome é usado naquele ponto. Para saber se o resultado foi conferido, abra o caso e veja o arquivo esperado e o status exigido. Em testes unitários, procure a chamada de VERIFICA em volta do uso.

Por que a página mostra um trecho de teste e não um exemplo “bonito”?​

Porque o trecho é código que o repositório realmente compila. Exemplos editoriais são úteis, mas não têm a mesma força de evidência. Quando existe um contrato com exemplo, a página mostra os dois.

O permalink usa o commit do build. Se você editar o fonte sem regerar, o link continua apontando para a versão antiga — o que preserva a correspondência com a página, mas não mostra sua alteração local. Regenere o site para atualizar os permalinks.

Como citar esta documentação em um trabalho?​

Cite a página e o commit mostrado no link de fonte, e diga qual comando foi executado. Para números, prefira a saída literal do log (por exemplo, make test) à contagem estática da página.

O que é o inventário JSON e para que serve?​

É a saída determinística do gerador: nomes, aliases, tipo, arquivo, linha, assinatura, guards, chamadas e URL da página. Serve para auditoria e automação.

python3 -c "import json; d=json.load(open('website/static/api/inventario.json')); print(d['counts'])"