Renderer.render_symbol
Gerada por tools/gerar_documentacao.py. Definição: tools/documentacao/render.py:684.
Monta a página completa de um símbolo com contrato, fonte, testes e portabilidade.
Tipo: função Python · Visibilidade: pública · Arquivo: tools/documentacao/render.py.
Assinatura e expansão
def render_symbol(self, symbol: Symbol) -> None:
Parâmetros formais: self, symbol: Symbol.
Como funciona
Monta a página completa de um símbolo com contrato, fonte, testes e portabilidade.
Implementação completa · 111 linhas
def render_symbol(self, symbol: Symbol) -> None:
"""Monta a página completa de um símbolo com contrato, fonte, testes e portabilidade."""
contract = self.contract(symbol)
aliases = sorted(symbol.aliases)
title = symbol.name + (f" · {' · '.join(aliases)}" if aliases and symbol.kind == "macro" else "")
summary = contract.get("resumo") or (symbol.comment.splitlines()[0] if symbol.comment else "")
if not summary and symbol.kind == "macro":
body = symbol.body.strip()
category = self.macro_category(symbol)
group = self.contracts.get("macro_groups", {}).get(category, "")
summary = (f"Macro {'com argumentos' if symbol.parameters else 'de objeto'} que expande para `{body}`. "
+ group) if body else "Macro de objeto sem corpo de expansão."
contract = dict(contract)
contract.setdefault("mecanica", group or "A expansão literal abaixo é o contrato desta macro.")
if not summary and symbol.kind == "função C" and symbol.name == "main":
summary = "Ponto de entrada do transpilador: interpreta a CLI, orquestra leitura/tradução, trata erros de E/S e devolve o código de saída." if symbol.path.startswith("tools/") else "Ponto de entrada do harness: seleciona modos de stdin/falha fatal ou executa os grupos unitários e resume falhas."
if not summary and symbol.kind == "função C" and symbol.path.startswith("tests/"):
summary = f"Função do arquivo de teste `{symbol.path}`; o corpo abaixo e os casos associados mostram o cenário e o resultado conferido."
if not summary:
summary = f"{symbol.kind} definida em {symbol.path}; contrato extraído da assinatura e do corpo abaixo."
self.audit["sem_resumo_editorial"].append(symbol.key)
out = [f":::tip[Página gerada do fonte]\nGerada por `tools/gerar_documentacao.py`. "
f"Definição: {self.gh_link(symbol.path, symbol.line, label=f'{symbol.path}:{symbol.line}')}.\n:::\n\n",
protect(summary) + "\n\n"]
if symbol.kind == "macro":
out.append(f"**Tipo:** macro {'com argumentos' if symbol.parameters else 'de objeto'} · **Módulo/categoria:** {CAT_LABELS[self.macro_category(symbol)]}.\n\n")
if aliases:
out.append("**Nomes equivalentes:** " + ", ".join(f"`{a}`" for a in aliases) +
". Os testes de qualquer um desses nomes são reunidos nesta página.\n\n")
if symbol.name.startswith("BG_") and not aliases and symbol.path == "include/basicgol.h":
out.append("Não foi encontrado nome curto equivalente no cabeçalho atual; use a forma prefixada.\n\n")
else:
out.append(f"**Tipo:** {symbol.kind} · **Visibilidade:** {symbol.visibility} · **Arquivo:** `{symbol.path}`.\n\n")
out.append("## Assinatura e expansão\n\n" + fence(symbol.signature, code_language(symbol.path)))
if symbol.parameters:
out.append("**Parâmetros formais:** " + ", ".join(f"`{p}`" for p in symbol.parameters) + ".\n\n")
if symbol.kind == "macro":
out.append("**Corpo da macro:**\n\n" + fence(symbol.body or "(vazio)", "c"))
target = self.macro_target(symbol)
if target:
out.append(f"Encadeia para {self.link(target)}.\n\n")
if symbol.prototypes:
out.append("**Declarações públicas localizadas:**\n\n")
for proto in symbol.prototypes:
label = f"{proto['path']}:{proto['line']}"
out.append(f"- {self.gh_link(proto['path'], proto['line'], label=label)}\n")
if proto["comment"]:
out.append(quote(proto["comment"]))
out.append("\n")
out.append("## Como funciona\n\n")
mechanics = contract.get("mecanica") or symbol.comment
if mechanics:
out.append(protect(mechanics) + "\n\n")
else:
out.append("O comportamento normativo é o corpo extraído abaixo. Não foi inferida uma garantia adicional sem contrato/documentação no fonte.\n\n")
if contract.get("retorno"):
out.append("**Retorno:** " + protect(contract["retorno"]) + "\n\n")
if contract.get("cuidados"):
out.append(":::caution[Contrato e armadilhas]\n")
for note in contract["cuidados"]:
out.append("- " + protect(note) + "\n")
out.append(":::\n\n")
if contract.get("exemplo"):
out.append("## Exemplo de uso\n\n" + fence(contract["exemplo"], code_language(symbol.path)) + "\n")
if symbol.comment and symbol.comment != mechanics:
out.append("## Comentário do fonte\n\n" + quote(symbol.comment) + "\n")
if symbol.body and symbol.kind != "macro":
long = len(symbol.body.splitlines()) > 45
if long:
out.append(f"<details>\n<summary>Implementação completa · {len(symbol.body.splitlines())} linhas</summary>\n\n")
else:
out.append("## Implementação\n\n")
out.append(fence(symbol.body, code_language(symbol.path)) + "\n")
if long:
out.append("</details>\n\n")
related_macros = [m for m in self.canonical_macros if symbol.name in m.calls]
if related_macros:
out.append("## Interface BASICGOL relacionada\n\n" + ", ".join(self.link(m) for m in related_macros) + "\n\n")
deps = [n for n in symbol.calls if n in self.inv.by_name and n != symbol.name]
if deps:
links = []
for name in deps:
candidates = self.inv.by_name[name]
if len(candidates) == 1:
links.append(self.link(candidates[0]))
if links:
out.append("**Nomes internos referenciados:** " + ", ".join(links) + ".\n\n")
out.append("## Como este símbolo aparece nos testes\n\n")
out.append(self.render_refs(symbol))
out.append(self.render_modes(symbol))
out.append(self.indirect_refs(symbol))
if symbol.path == "tools/basicgolc.c":
match = re.search(r"verifica_w(\d+)", symbol.name)
if match:
cases = [c for c in self.inv.cases if c["name"].startswith("w" + match.group(1) + "_")]
if cases:
out.append("**Caso de aviso correspondente:** " + ", ".join(f"[{c['name']}](/testes/casos/{c['suite']}/{c['name']})" for c in cases) + ".\n\n")
out.append(":::note[Testes de caixa-preta]\nO transpilador é exercitado pela CLI em `tests/run.sh`, "
"`tests/run_portabilidade.sh` e `tests/fuzz_basicgolc.py`. Uma ligação no grafo de chamadores "
"não prova que cada ramo desta função foi coberto.\n:::\n\n")
out.append(self.portability(symbol))
out.append(self.integration_checklist(symbol))
out.append(self.symbol_faq(symbol, contract, summary))
if symbol.kind == "macro":
folder = f"referencia/linguagem/{self.macro_category(symbol)}"
label = next((a for a in aliases if not a.startswith("BG_")), symbol.name)
self.page(self.slug(symbol), title, "".join(out), label=label, description=summary)
elif symbol.kind == "função C" and symbol.path.startswith(("include/", "src/")):
self.page(self.slug(symbol), title, "".join(out), label=symbol.name, description=summary)
else:
self.page(self.slug(symbol), title, "".join(out), label=symbol.name, description=summary)
Nomes internos referenciados: code_language, fence, protect, quote.
Como este símbolo aparece nos testes
Nenhuma referência direta a este nome foi encontrada nos arquivos de teste. Isso pode ser esperado para guardas de inclusão, configuração ou código exercitado indiretamente; não é uma afirmação de cobertura zero.
Compiladores, padrão C e sistema operacional
Nenhum ramo condicional externo foi detectado para este símbolo. A implementação é compartilhada no fonte; isso não certifica compiladores ou sistemas não executados.
- Script Python: usa a biblioteca padrão e pathlib/subprocess quando aplicável; caminhos não devem depender do separador de um único OS.
A matriz histórica distingue executado, compilado, avaliado e não testado. Consulte a matriz, os compiladores e os logs atuais dos workflows antes de chamar um alvo de suportado.
Perguntas frequentes
Perguntas reunidas a partir da definição, do contrato editorial e dos testes de Renderer.render_symbol. As respostas repetem apenas o que o repositório mostra; quando não há evidência, isso é dito.
Em uma frase, o que Renderer.render_symbol faz?
Monta a página completa de um símbolo com contrato, fonte, testes e portabilidade.
Qual é a assinatura e o tipo de retorno de Renderer.render_symbol?
Assinatura extraída de tools/documentacao/render.py; visibilidade pública.
def render_symbol(self, symbol: Symbol) -> None:
Como chamar Renderer.render_symbol corretamente?
Nenhum exemplo editorial nem chamada direta em teste foi localizada. A forma de uso é a assinatura acima; os chamadores aparecem na seção de evidência indireta quando existem.
def render_symbol(self, symbol: Symbol) -> None:
Por que não há teste direto para Renderer.render_symbol?
A busca estática não encontrou o identificador nos arquivos de teste. Isso é esperado para guardas de inclusão, configuração de build e nomes alcançados apenas por chamadores internos. O JSON de cobertura registra a lacuna em vez de convertê-la em aprovação.
Renderer.render_symbol depende de compilador, padrão C ou sistema operacional?
Renderer.render_symbol é uma função Python: requer Python 3.10+ e biblioteca padrão, sem compilador C.
O que acontece em caso de falha ou uso inválido?
Não há ressalva editorial específica para este nome. O comportamento em falha é o do corpo/expansão mostrado acima; não invente validação que o fonte não faz.