138 lines
8.0 KiB
Markdown
138 lines
8.0 KiB
Markdown
---
|
|
id: DEC-0039
|
|
ticket: pbs-symbol-documentation-and-hover-markdown
|
|
title: PBS symbol documentation with Doc markdown text blocks
|
|
status: accepted
|
|
created: 2026-07-15
|
|
ref_agenda: AGD-0039
|
|
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
|
|
---
|
|
|
|
## Context
|
|
|
|
PBS editor assistance needs hover content that can explain author intent, API contracts, parameter meaning, semantic constraints, and usage notes. Existing symbol surfaces can expose mechanical information such as kind, signature, origin, and type/shape, but PBS does not yet define a canonical authored documentation model.
|
|
|
|
This decision belongs to domain owner `compiler/pbs`.
|
|
|
|
Touched subdomains:
|
|
|
|
- `compiler/general`
|
|
- `studio/lsp`
|
|
- `tools/vscode-extension`
|
|
|
|
This decision resolves `AGD-0039`. It does not replace the existing wave-1 editor-assistance work; it defines the source-language and compiler-backed documentation model that hover, completion, signature help, stdlib documentation, and future editor consumers can reuse.
|
|
|
|
## Decision
|
|
|
|
PBS MUST support explicit authored documentation for named API declarations through a reserved `[Doc]` attribute.
|
|
|
|
The only canonical v1 shape is:
|
|
|
|
```pbs
|
|
[Doc(markdown = """
|
|
Draws a sprite.
|
|
|
|
- `x`: screen x
|
|
- `y`: screen y
|
|
""")]
|
|
```
|
|
|
|
`Doc` MUST be a reserved compiler-recognized attribute name. It MUST NOT be treated as an ordinary user-defined attribute with language-specific reinterpretation.
|
|
|
|
`Doc` MUST use a single required argument named `markdown`. The `markdown` argument MUST use a triple-quoted documentation text block as its payload. The v1 surface MUST NOT accept aliases or alternate forms such as `text`, positional arguments, `html`, `format`, `Document`, `Documentation`, or `md"""..."""`.
|
|
|
|
`[Doc]` MUST attach to the declaration immediately following it, following the normal PBS attribute association rule. Attribute order MUST be semantically irrelevant; `[Doc]` before or after other attributes on the same declaration MUST produce the same documentation result.
|
|
|
|
`[Doc]` MUST be valid only on named API declarations that introduce named semantic symbols and can carry attributes. The v1 documentable surface includes:
|
|
|
|
- functions;
|
|
- methods;
|
|
- classes/structs, when present in the PBS declaration surface;
|
|
- services;
|
|
- hosts;
|
|
- builtin and stdlib declarations;
|
|
- interface declarations.
|
|
|
|
Parameters MUST NOT receive `[Doc]` in v1 under any circumstance. Parameter documentation, when needed, MUST be authored inside the Markdown payload of the owning declaration.
|
|
|
|
Fields, enum cases, tuple fields, local variables, expressions, and other non-API declaration surfaces MUST NOT receive `[Doc]` unless a future decision explicitly classifies them as named API declarations documentable by `[Doc]`.
|
|
|
|
The `markdown` payload MUST be a PBS documentation text block, not a general runtime string literal. `"""..."""` MUST NOT become a general PBS runtime string literal as part of this decision.
|
|
|
|
The documentation text block MUST be normalized before semantic validation and before exposure to editor consumers. Normalization MUST:
|
|
|
|
- remove an incidental leading empty line after the opening delimiter;
|
|
- remove an incidental trailing empty line before the closing delimiter;
|
|
- compute the common indentation of non-empty content lines;
|
|
- remove that common indentation;
|
|
- preserve internal line breaks;
|
|
- preserve Markdown content after indentation normalization.
|
|
|
|
After normalization, an empty or whitespace-only documentation payload MUST be rejected.
|
|
|
|
The authored documentation format for PBS v1 MUST be a supported Markdown subset. PBS defines Markdown as the documentation protocol, not as a guarantee that every client renders every Markdown construct identically.
|
|
|
|
The compiler MUST preserve normalized Markdown documentation as semantic metadata of the documented symbol. LSP and editor consumers MUST consume compiler-resolved documentation metadata; they MUST NOT reparse PBS source to discover documentation.
|
|
|
|
`[Doc]` MUST be compile/editor metadata. It MUST NOT be lowered into runtime or cartridge artifacts unless a future runtime or packaging decision explicitly requires that.
|
|
|
|
Stdlib, SDK, and interface modules MUST use the same `[Doc(markdown = """...""")]` model for authored documentation. If imported or generated documentation exists in the future, authored source documentation MUST take precedence. Conflicts MUST be deterministic or produce explicit diagnostics.
|
|
|
|
## Rationale
|
|
|
|
An explicit attribute keeps documentation attached to language-owned semantic symbols instead of relying on proximity between comments and declarations. This avoids a separate comment-binding model and gives the compiler one canonical source of truth for editor assistance.
|
|
|
|
The short attribute name `Doc` is practical at the authoring site and remains clear when paired with the required `markdown` argument. The argument name carries the payload format, so a prefixed literal such as `md"""..."""` would add lexer and grammar surface without enough v1 benefit.
|
|
|
|
Restricting the v1 shape to `[Doc(markdown = """...""")]` protects maintainability. It avoids aliases, ambiguous forms, and compatibility pressure around multiple documentation payload formats.
|
|
|
|
Restricting triple-quoted text blocks to documentation avoids accidentally introducing general multiline runtime strings. Runtime strings raise separate questions about type behavior, lowering, constant pools, equality, escapes, and artifact representation; those questions do not belong to this documentation decision.
|
|
|
|
Compiler ownership keeps hover, completion, signature help, stdlib docs, and future editor consumers aligned. The LSP layer should transport resolved documentation, not infer language semantics from raw source text.
|
|
|
|
## Implications
|
|
|
|
- PBS syntax and parsing MUST recognize triple-quoted documentation text blocks in `[Doc(markdown = ...)]`.
|
|
- PBS semantic validation MUST enforce the canonical `Doc` shape, allowed declaration sites, duplicate detection, empty-payload rejection, and invalid-argument diagnostics.
|
|
- A declaration MUST NOT have more than one `[Doc]`; duplicates MUST be semantic errors rather than parse errors.
|
|
- Formatter implementations MUST preserve the internal Markdown text of documentation blocks and MUST NOT reflow authored Markdown.
|
|
- Rename/refactor tools are not required in this phase to update textual references inside Markdown documentation.
|
|
- Specs and stdlib documentation authored for repository-owned surfaces MUST be written in English.
|
|
- Tests SHOULD validate normalized Markdown payloads at compiler and LSP boundaries. VSCode visual validation may remain manual for this wave.
|
|
- Hover composition may be implemented later, but the ownership boundary is fixed: compiler resolves documentation, LSP transports it, and the editor renders it.
|
|
|
|
## Propagation Targets
|
|
|
|
- specs:
|
|
- `docs/specs/compiler-languages/pbs/3. Core Syntax Specification.md`
|
|
- `docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md`
|
|
- `docs/specs/compiler-languages/pbs/11. AST Specification.md`
|
|
- `docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md`
|
|
- `docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
|
- LSP/editor-facing specs if/when a dedicated Studio/LSP spec surface exists.
|
|
- plans:
|
|
- Create an implementation plan for syntax, AST, semantics, documentation metadata, LSP exposure, tests, and stdlib authoring.
|
|
- code:
|
|
- PBS lexer/parser/AST.
|
|
- PBS semantic validation and symbol/editorial surfaces.
|
|
- LSP hover/editorial transport.
|
|
- Stdlib/interface PBS sources.
|
|
- tests:
|
|
- Lexer/parser coverage for documentation text blocks.
|
|
- Semantic diagnostics for invalid `Doc` usage.
|
|
- Normalization tests for indentation and empty payloads.
|
|
- Compiler/editorial surface tests proving documentation is attached to resolved symbols.
|
|
- LSP hover or symbol-documentation payload tests.
|
|
- docs:
|
|
- PBS language specs.
|
|
- Any lessons generated after implementation and housekeeping.
|
|
|
|
## References
|
|
|
|
- Agenda: AGD-0039
|
|
- Source discussion: DSC-0036
|
|
|
|
## Revision Log
|
|
|
|
- 2026-07-15: Initial decision drafted from accepted `AGD-0039`.
|