188 lines
10 KiB
Markdown
188 lines
10 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: accepted
|
|
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 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:
|
|
|
|
```pbs
|
|
[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.
|