prometeu-studio/discussion/workflow/agendas/AGD-0039-pbs-symbol-documentation-and-hover-markdown.md

id	ticket	title	status	created	tags
AGD-0039	pbs-symbol-documentation-and-hover-markdown	Modelo de documentacao de simbolos em PBS e consumo markdown no hover	accepted	2026-05-08	compiler compiler-pbs studio lsp vscode editor hover documentation markdown

Pain

A wave atual de assistencia editorial quer hover util, mas ainda nao existe um modelo claro para documentacao authored dentro de PBS.

Sem esse modelo, o hover pode até mostrar:

• kind;
• assinatura;
• origem;
• tipo/shape.

Mas continua sem uma superficie limpa para explicar intencao de uso, contrato semantico, detalhes de parametros ou observacoes de API.

Hoje a direcao consolidada eh algo como:

• [Doc(markdown = """qualquer markdown aqui dentro...""")]

como anotacao consumida diretamente pelo hover.

Isso parece simples no uso, mas toca em decisoes de linguagem e contrato editorial que merecem discussao propria.

Context

Domain owner: compiler/pbs

Subdomains touched:

• compiler/general
• studio/lsp
• tools/vscode-extension

Esta agenda eh deliberadamente separada de AGD-0038.

Razao:

• AGD-0038 trata da wave 1 de completion, hover e signature help;
• esta nova agenda trata da autoria, armazenamento, propagacao e consumo de documentacao de simbolos.

O objetivo eh evitar que a primeira wave de assistencia editorial fique bloqueada por uma decisao de linguagem ainda nao fechada.

Open Questions

• A autoria da documentacao deve acontecer por anotacao explicita como [Doc(...)], por comentario estruturado, ou por outro mecanismo?
• O payload authored deve aceitar um subset Markdown como fonte canonica, ou deve haver outra normalizacao/restricao?
• Quais declaracoes nomeadas de API podem carregar documentacao na wave inicial: funcoes, methods, classes/structs, services, hosts, builtin/stdlib declarations e interface declarations?
• A documentacao deve viver no AST/semantics como superficie compiler-backed explicita?
• Como a documentacao authored em PBS se relaciona com documentacao de stdlib gerada ou importada de outras fontes?
• O hover deve consumir markdown pronto sem transformacao, ou deve haver um pipeline intermediario de sanitizacao/normalizacao?
• Como tratar multilinhas, escaping e ergonomia de escrita se a surface for [Doc(...)]?
• A agenda deve definir apenas o modelo de autoria, ou tambem o transporte LSP e a composicao final do hover?

Options

Option A - Anotacao [Doc(...)] com Markdown subset como payload canonico

• Approach: introduzir uma anotacao explicita na linguagem PBS cujo conteudo ja eh markdown pronto para o hover.
• Pro: autoria direta, intencao clara, pipeline simples de consumo no LSP e no hover.
• Con: precisa desenhar sintaxe, escaping, multiline e regras de onde a anotacao eh permitida.
• Maintainability: forte se a surface de linguagem ficar limpa.

Option B - Comentarios estruturados como fonte de documentacao

• Approach: usar comentarios especiais ou doc-comments, com parser especifico para gerar documentacao de simbolo.
• Pro: mais familiar para quem vem de outras linguagens e menos intrusivo no corpo semantico da linguagem.
• Con: exige novo contrato de binding entre comentarios e simbolos, e pode aumentar ambiguidade editorial.
• Maintainability: media.

Option C - Nao definir autoria em PBS agora e suportar apenas docs de stdlib por metadata externa

• Approach: deixar a linguagem sem surface authored por enquanto e alimentar hover apenas com docs externas/geradas.
• Pro: menor custo imediato de linguagem.
• Con: resolve mal a autoria de codigo de usuario e deixa o modelo incompleto.
• Maintainability: fraca.

Tradeoffs

Option C nao parece suficiente como direcao de produto se a intencao eh ter hover realmente util para APIs authored em PBS.

Option B eh plausivel, mas move o problema para um binding entre comentario e simbolo que tambem precisa ser projetado com cuidado. Isso costuma parecer mais barato do que realmente eh.

Option A tem um custo claro de sintaxe e modelo, mas pelo menos deixa explicito que documentacao eh metadado semantico e nao apenas texto solto ao redor do codigo.

Se a equipe realmente quer markdown authored pronto para consumo no hover, Option A parece a discussao mais direta e honesta.

Recommendation

Discutir esta agenda com viés inicial para Option A e fechar a decision com um shape canonico unico:

[Doc(markdown = """
Draws a sprite.

- `x`: screen x
- `y`: screen y
""")]

O consenso da discussao eh que Doc eh curto e pratico, e que o nome do argumento markdown ja carrega a semantica do payload. Um prefixo lexical como md"""...""" nao deve entrar na v1 porque adiciona uma nova familia de literais antes de haver necessidade concreta para multiplos payloads especializados.

A recomendacao preliminar eh separar o problema em duas perguntas:

1. qual eh a surface canonical de autoria da documentacao em PBS?
2. como essa documentacao vira um payload editorial resolvido para hover e futuros consumers?

Mesmo que [Doc(...)] seja a direcao vencedora, a decision deve deixar claro:

• onde ela pode ser usada;
• qual formato textual aceita;
• como ela eh preservada no compiler;
• como chega ao LSP;
• e como o hover deve compor isso com assinatura e metadados do simbolo.

Proposed Resolution

Fechar a agenda com a seguinte direcao:

• PBS deve suportar documentacao explicita de simbolos por atributo [Doc(markdown = """...""")].
• Doc deve ter um unico shape canonico na v1: argumento nomeado markdown com payload em triple-quoted text block.
• O atributo segue a regra normal de atributos PBS: associa-se a declaracao imediatamente seguinte.
• [Doc] deve ser valido para declaracoes nomeadas de API que introduzem simbolo semantico nomeado e que possam carregar atributos, incluindo funcoes, methods, classes/structs, services, hosts, builtin/stdlib declarations e interface declarations.
• Parametros nao devem receber [Doc] na v1 em nenhuma situacao; a documentacao de parametros deve viver no Markdown da declaracao que os possui.
• A intencao normativa eh nao limitar artificialmente declaracoes documentaveis por origem; se algum ponto da gramatica de declaracao ainda nao aceita atributos, o plano deve tratar isso como trabalho sintatico explicito.
• A ordem entre [Doc] e outros atributos deve ser irrelevante.
• Mais de um [Doc] no mesmo simbolo deve ser erro semantico, nao erro de parse.
• [Doc] sem markdown, com argumentos extras, com payload vazio/whitespace-only, ou aplicado fora da superficie documentavel deve produzir diagnostico claro.
• O payload """...""" deve ser tratado inicialmente como text block documental, nao como string runtime geral de PBS.
• O text block deve aplicar normalizacao de indentacao equivalente ao modelo de text blocks de Java/Javadoc: remover linhas externas vazias incidentais, calcular indentacao comum das linhas nao vazias, remover essa indentacao comum, preservar quebras internas e preservar o conteudo Markdown.
• O compiler deve preservar o Markdown normalizado como metadata semantica do simbolo.
• O LSP e demais consumers devem consumir documentacao resolvida pelo compiler; nao devem reparsear source para descobrir docs.
• Um subset Markdown deve ser o protocolo de documentacao authored em PBS.
• O Markdown deve ser definido como payload editorial preservado, nao como garantia de renderizacao identica em todos os clientes. Renderizacao, sanitizacao e suporte a constructs especificos sao responsabilidades do consumer.
• Formatters devem preservar o conteudo interno do text block e nao devem reflowar Markdown authored.
• Rename/refactor nao precisa atualizar referencias textuais dentro do Markdown nesta fase do projeto.
• Specs e documentacao da stdlib devem ser escritas em ingles.
• Testes devem validar o payload Markdown normalizado no compiler/LSP; validacao visual no VSCode pode ser manual.
• Stdlib, SDK e interface modules devem usar o mesmo modelo [Doc(markdown = """...""")] para documentacao authored.
• Se no futuro houver documentacao importada ou gerada, documentacao authored no source deve ter precedencia, e conflitos devem ter regra deterministica ou diagnostico explicito.

Maintenance Friction Points

Pontos que a decision e o plano devem proteger para evitar que uma feature simples de editor vire divida de linguagem:

• "Todas as declaracoes nomeadas de API documentaveis" precisa ser especificado como "toda declaracao de API que introduz simbolo semantico nomeado", evitando ambiguidade sobre parametros, fields, enum cases, tuple fields, expressoes e variaveis locais.
• A gramatica de atributos pode precisar ser expandida para declaracoes que hoje ainda nao aceitam atributos; isso deve ser tratado como parte real do trabalho, nao como excecao informal.
• A v1 nao deve aceitar aliases como text, argumento posicional, html, format, Document, Documentation, ou md"""...""".
• """...""" nao deve virar literal runtime geral sem uma decision propria.
• A normalizacao do text block deve ser especificada no texto normativo, nao apenas referenciada informalmente como "igual Java".
• Parametros nao recebem [Doc] na v1; fields, enum cases e tuple fields so devem receber [Doc] se a decision os classificar explicitamente como declaracoes nomeadas de API documentaveis.
• O formatter futuro eh um ponto sensivel: ele pode alinhar a declaracao, mas nao pode alterar o Markdown authored dentro do text block.
• A composicao visual do hover pode ficar para plano/implementacao, mas a ownership deve ficar clara: compiler resolve documentacao; LSP transporta; editor renderiza.

Discussion

Esta agenda nao deve ser reduzida a "mostrar markdown no hover".

O problema real eh definir ownership e boundary da documentacao:

• o author escreve onde?
• o compiler preserva como?
• o LSP transporta em qual shape?
• o hover monta o resultado com qual ordem e responsabilidade?

Tambem vale observar que a escolha aqui pode influenciar mais do que hover:

• completions futuras podem querer detail e documentation;
• signature help pode querer descricoes de parametros;
• docs de stdlib podem querer surface unificada com docs authored.

Por isso, mesmo sendo uma agenda separada, ela conversa diretamente com a futura qualidade do editor.

Resolution

Consenso de agenda formado em favor de [Doc(markdown = """...""")] como anotacao explicita, compiler-owned, com payload em subset Markdown e text block documental normalizado.

Next Step

Aceitar a agenda e fechar uma decision propria para o modelo de documentacao de simbolos em PBS.