implements PLN-0092
This commit is contained in:
+63
-13
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user