Renderer.category_faq
Gerada por tools/gerar_documentacao.py. Definição: tools/documentacao/render.py:441.
FAQ de uma família de macros, montado com nomes e expansões reais.
Tipo: função Python · Visibilidade: pública · Arquivo: tools/documentacao/render.py.
Assinatura e expansão
def category_faq(self, category: str, label: str, symbols: list[Symbol]) -> str:
Parâmetros formais: self, category: str, label: str, symbols: list[Symbol].
Como funciona
FAQ de uma família de macros, montado com nomes e expansões reais.
Implementação
def category_faq(self, category: str, label: str, symbols: list[Symbol]) -> str:
"""FAQ de uma família de macros, montado com nomes e expansões reais."""
names = sorted(s.name for s in symbols)
short = [a for s in symbols for a in sorted(s.aliases) if not a.startswith("BG_")]
ordered = sorted(symbols, key=lambda s: s.name)
sample = next((s for s in ordered if self.contract(s).get("exemplo")), ordered[0])
sample_code = (self.contract(sample).get("exemplo") or sample.body or sample.signature).strip()
with_refs = next((s for s in ordered if self.usage_snippet(s)), None)
usage = self.usage_snippet(with_refs) if with_refs else None
items = [
{"q": f"Quais nomes pertencem a “{label}”?",
"a": [f"Esta família reúne **{len(names)} contrato(s)**: " +
", ".join(f"`{n}`" for n in names[:12]) +
(f" e mais {len(names) - 12}." if len(names) > 12 else ".") +
(f" As formas curtas incluem {', '.join(f'`{s}`' for s in short[:10])}." if short else "")]},
{"q": "Como colocar um destes nomes no meu programa?",
"a": ["Inclua o cabeçalho uma única vez e compile em C11. Não é necessário declarar "
"nada à mão: cada nome é macro do cabeçalho.",
f"Trecho de `{sample.name}`:"],
"code": "#include <basicgol.h>\n\n" + sample_code, "lang": "c"},
{"q": "Qual é a diferença entre a forma curta e a forma `BG_*`?",
"a": ["São o mesmo nome: a forma curta é um alias textual da canônica e ambas são "
"reunidas na mesma página de referência. Os testes de qualquer alias contam como "
"evidência da macro."],
"code": (lambda s: f"{s.name} /* forma canônica */\n" +
"".join(f"{a} /* alias equivalente */\n" for a in sorted(s.aliases))
if s.aliases else f"{sample.name} /* sem alias curto nesta versão */")(sample),
"lang": "c"},
{"q": "Estes nomes funcionam fora de C11?",
"a": ["Não. O cabeçalho recusa C99/C89 com mensagem explícita e usa `_Generic` para "
"selecionar formatos e divisões. Compiladores e sistemas operacionais continuam "
"sendo os do alvo; consulte a [matriz de compatibilidade](/projeto/11-matriz-compatibilidade)."]},
]
if usage:
text, lang, where = usage
items.append({"q": f"Como uma macro desta família aparece em uso real?",
"a": [f"Trecho de `{where}`:"], "code": text, "lang": lang})
return self.faq(
f"Perguntas frequentes sobre a família “{label}”, respondidas com as definições e os "
"usos que o gerador encontrou no repositório.", items)
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.category_faq. As respostas repetem apenas o que o repositório mostra; quando não há evidência, isso é dito.
Em uma frase, o que Renderer.category_faq faz?
FAQ de uma família de macros, montado com nomes e expansões reais.
Qual é a assinatura e o tipo de retorno de Renderer.category_faq?
Assinatura extraída de tools/documentacao/render.py; visibilidade pública.
def category_faq(self, category: str, label: str, symbols: list[Symbol]) -> str:
Como chamar Renderer.category_faq 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 category_faq(self, category: str, label: str, symbols: list[Symbol]) -> str:
Por que não há teste direto para Renderer.category_faq?
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.category_faq depende de compilador, padrão C ou sistema operacional?
Renderer.category_faq é 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.