64 lines
3.3 KiB
Markdown
64 lines
3.3 KiB
Markdown
---
|
|
id: PLN-0092
|
|
ticket: pbs-symbol-documentation-and-hover-markdown
|
|
title: Specify PBS Doc attribute and markdown text block syntax
|
|
status: done
|
|
created: 2026-07-15
|
|
ref_decisions: [DEC-0039]
|
|
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
Update the PBS normative specs so `DEC-0039` is reflected before code changes begin. This plan is the specification gate for the `[Doc(markdown = """...""")]` feature.
|
|
|
|
## Objective
|
|
|
|
Define the syntax, static semantics, AST shape, diagnostics, and stdlib documentation policy for compiler-owned PBS symbol documentation.
|
|
|
|
## Dependencies
|
|
|
|
- Requires accepted decision `DEC-0039`.
|
|
- Must be completed before parser, semantic, LSP, and stdlib implementation plans are accepted as complete.
|
|
|
|
## Scope
|
|
|
|
- Add `[Doc(markdown = """...""")]` to the PBS attribute surface.
|
|
- Define triple-quoted documentation text blocks as documentation-only payloads, not runtime strings.
|
|
- Define documentable named API declarations and explicitly exclude parameters.
|
|
- Define normalization, duplicate handling, invalid shape diagnostics, and non-runtime lowering rules.
|
|
|
|
## Non-Goals
|
|
|
|
- Implement lexer, parser, semantics, or LSP code.
|
|
- Define general multiline runtime strings.
|
|
- Define VSCode rendering details beyond the compiler/LSP ownership boundary.
|
|
|
|
## Execution Method
|
|
|
|
1. Update `docs/specs/compiler-languages/pbs/3. Core Syntax Specification.md` with the canonical `[Doc(markdown = """...""")]` syntax, allowed declaration sites, attribute ordering rule, and text block delimiter rules.
|
|
2. Update `docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md` with reserved `Doc` validation, duplicate rejection, parameter exclusion, empty normalized payload rejection, and non-documentable target diagnostics.
|
|
3. Update `docs/specs/compiler-languages/pbs/11. AST Specification.md` with an AST representation for documentation attributes and documentation text block payloads.
|
|
4. Update `docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md` with required diagnostic categories for unterminated text block, invalid `Doc` shape, duplicate `Doc`, empty payload, and invalid target.
|
|
5. Update `docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md` with the rule that stdlib, SDK, and interface modules use the same authored `Doc` surface.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- Specs define all normative rules from `DEC-0039` without deferring syntax or semantics to implementation judgment.
|
|
- The specs explicitly state that `"""..."""` is documentation-only for this feature.
|
|
- The specs explicitly state that parameters never receive `[Doc]` in v1.
|
|
- The specs identify propagation boundaries: compiler resolves, LSP transports, editor renders.
|
|
|
|
## Tests
|
|
|
|
- Run any existing spec conformance tests that validate PBS spec references.
|
|
- No code behavior tests are required in this plan.
|
|
|
|
## Affected Artifacts
|
|
|
|
- `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`
|