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	open	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 ideia proposta eh algo como:

• Document(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 Document(...), por comentario estruturado, ou por outro mecanismo?
• O payload authored deve aceitar markdown arbitrario como fonte canonica, ou deve haver alguma normalizacao/restricao?
• Quais simbolos podem carregar documentacao na wave inicial: funcoes, methods, services, hosts, builtin types, structs, enums, fields, constructors?
• 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 Document(...)?
• A agenda deve definir apenas o modelo de autoria, ou tambem o transporte LSP e a composicao final do hover?

Options

Option A - Anotacao Document(...) com markdown 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, mas sem fechar ainda a sintaxe final.

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 Document(...) seja a direcao vencedora, a decisao 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.

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

Ainda em aberto.

Next Step

Se o enquadramento fizer sentido, o proximo passo eh discutir as open questions e fechar uma decision propria para o modelo de documentacao de simbolos em PBS.