implements PLN-0092

This commit is contained in:
2026-07-15 06:55:26 +01:00
parent ad2ae00f39
commit 917b0e1b9a
19 changed files with 955 additions and 18 deletions
@@ -2,7 +2,7 @@
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
status: accepted
created: 2026-05-08
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
---
@@ -20,9 +20,9 @@ Sem esse modelo, o hover pode até mostrar:
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:
Hoje a direcao consolidada eh algo como:
- `Document(qualquer markdown aqui dentro...)`
- `[Doc(markdown = """qualquer markdown aqui dentro...""")]`
como anotacao consumida diretamente pelo hover.
@@ -49,19 +49,19 @@ O objetivo eh evitar que a primeira wave de assistencia editorial fique bloquead
## 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 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 `Document(...)`?
- 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 `Document(...)` com markdown como payload canonico
### 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.
@@ -94,14 +94,25 @@ Se a equipe realmente quer markdown authored pronto para consumo no hover, Optio
## Recommendation
Discutir esta agenda com viés inicial para **Option A**, mas sem fechar ainda a sintaxe final.
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 `Document(...)` seja a direcao vencedora, a decisao deve deixar claro:
Mesmo que `[Doc(...)]` seja a direcao vencedora, a decision deve deixar claro:
- onde ela pode ser usada;
- qual formato textual aceita;
@@ -109,6 +120,45 @@ Mesmo que `Document(...)` seja a direcao vencedora, a decisao deve deixar claro:
- 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".
@@ -130,8 +180,8 @@ Por isso, mesmo sendo uma agenda separada, ela conversa diretamente com a futura
## Resolution
Ainda em aberto.
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
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.
Aceitar a agenda e fechar uma `decision` propria para o modelo de documentacao de simbolos em PBS.