--- id: AGD-0039 ticket: pbs-symbol-documentation-and-hover-markdown title: Modelo de documentacao de simbolos em PBS e consumo markdown no hover status: open created: 2026-05-08 tags: [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.