Renderer.render_refs
Gerada por tools/gerar_documentacao.py. Definição: tools/documentacao/render.py:519.
Renderiza arquivos, linhas, contextos e trechos de uso em testes.
Tipo: função Python · Visibilidade: pública · Arquivo: tools/documentacao/render.py.
Assinatura e expansão
def render_refs(self, symbol: Symbol) -> str:
Parâmetros formais: self, symbol: Symbol.
Como funciona
Renderiza arquivos, linhas, contextos e trechos de uso em testes.
Implementação
def render_refs(self, symbol: Symbol) -> str:
"""Renderiza arquivos, linhas, contextos e trechos de uso em testes."""
refs = [r for r in self.direct_refs(symbol) if r.kind != "tabela de expansão"]
if not refs:
return (":::note[Sem uso direto localizado]\n"
"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.\n:::\n")
groups: dict[str, list[Reference]] = defaultdict(list)
for ref in refs:
groups[ref.path].append(ref)
out = [f"**{len(refs)} ocorrência(s) em {len(groups)} arquivo(s) de teste.** ",
"Os links apontam para linhas exatas; os trechos mostram o contexto local. ",
"Uma menção não prova que todos os ramos foi executado.\n\n"]
for path, items in sorted(groups.items()):
containers = sorted({r.container for r in items})
lines = sorted({r.line for r in items})
kinds = sorted({r.kind for r in items})
label = path if "::" not in path else f"{items[0].parent} · heredoc na linha {items[0].offset + 1}"
out.append(f"### {label}\n\n")
out.append(f"Contexto: {', '.join('`' + c + '`' for c in containers[:8])}{' …' if len(containers) > 8 else ''}. ")
out.append(f"Linhas: {', '.join(str(n) for n in lines[:35])}{' …' if len(lines) > 35 else ''}. ")
out.append(f"Tipo de evidência: {', '.join(kinds)}; via {', '.join(sorted({r.symbol for r in items}))}.\n\n")
intervals = []
for line in lines:
lo, hi = max(1, line - 2), line + 2
if intervals and lo <= intervals[-1][1] + 1:
intervals[-1][1] = max(intervals[-1][1], hi)
else:
intervals.append([lo, hi])
for lo, hi in intervals[:6]:
text, start, stop, real = self.source_snippet(path, lo, context=0, end=hi)
out.append(f"<details>\n<summary>Linhas {start}–{stop} · abrir contexto</summary>\n\n")
out.append(fence(text, code_language(real)) + "\n")
out.append(self.gh_link(real, start, label="Ver no GitHub") + "\n\n</details>\n\n")
if len(intervals) > 6:
out.append(f"_{len(intervals) - 6} outros blocos de contexto: use os links de linha e o JSON de inventário._\n\n")
expansions = [r for r in self.direct_refs(symbol) if r.kind == "tabela de expansão"]
if expansions:
out.append("Também aparece na tabela de expansão conferida por `cc -E -dM`: " +
", ".join(self.gh_link(r.path, r.line, label=f"L{r.line}") for r in expansions) + ".\n")
return "".join(out)
Nomes internos referenciados: code_language, fence.
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_refs. 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_refs faz?
Renderiza arquivos, linhas, contextos e trechos de uso em testes.
Qual é a assinatura e o tipo de retorno de Renderer.render_refs?
Assinatura extraída de tools/documentacao/render.py; visibilidade pública.
def render_refs(self, symbol: Symbol) -> str:
Como chamar Renderer.render_refs 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_refs(self, symbol: Symbol) -> str:
Por que não há teste direto para Renderer.render_refs?
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_refs depende de compilador, padrão C ou sistema operacional?
Renderer.render_refs é 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.