138 lines
5.6 KiB
Markdown
138 lines
5.6 KiB
Markdown
---
|
|
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.
|