65 lines
2.5 KiB
Markdown
65 lines
2.5 KiB
Markdown
---
|
|
id: PLN-0096
|
|
ticket: pbs-symbol-documentation-and-hover-markdown
|
|
title: Validate Doc attribute semantics and diagnostics
|
|
status: open
|
|
created: 2026-07-15
|
|
ref_decisions: [DEC-0039]
|
|
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
Enforce the semantic contract of `[Doc]` after syntax can represent it.
|
|
|
|
## Objective
|
|
|
|
Reject invalid `Doc` usage and produce clear diagnostics for all invalid shapes and targets required by `DEC-0039`.
|
|
|
|
## Dependencies
|
|
|
|
- Depends on `PLN-0092`.
|
|
- Depends on `PLN-0094`.
|
|
- Depends on `PLN-0095`.
|
|
|
|
## Scope
|
|
|
|
- Reserve `Doc` as a compiler-recognized attribute.
|
|
- Accept only `Doc(markdown = """...""")`.
|
|
- Reject aliases, positional arguments, extra arguments, duplicate `Doc`, empty normalized payload, parameter targets, and non-documentable targets.
|
|
- Keep duplicates as semantic errors rather than parse errors.
|
|
|
|
## Non-Goals
|
|
|
|
- Attach documentation to final symbol metadata.
|
|
- Expose documentation through LSP.
|
|
- Author stdlib documentation.
|
|
|
|
## Execution Method
|
|
|
|
1. Locate existing declaration and reserved attribute validators, including `PbsDeclarationSemanticsValidator`, `PbsDeclarationRuleValidator`, and interface-module reserved attribute checks.
|
|
2. Add `Doc` validation in the semantic phase that already validates declaration attributes.
|
|
3. Define allowed declaration categories according to the spec: named API declarations that can carry attributes.
|
|
4. Add or extend `PbsSemanticsErrors` diagnostics for invalid `Doc` target, invalid shape, duplicate attribute, missing `markdown`, extra arguments, and empty payload.
|
|
5. Add tests covering valid declaration targets and every invalid case.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- Every invalid shape named by `DEC-0039` produces a semantic diagnostic.
|
|
- Parameters never accept `[Doc]`.
|
|
- Duplicate `[Doc]` on one declaration is rejected semantically.
|
|
- Existing reserved attributes keep their current behavior.
|
|
|
|
## Tests
|
|
|
|
- `PbsSemanticsDeclarationsTest`
|
|
- `PbsInterfaceModuleSemanticsTest`
|
|
- `PbsDiagnosticsContractTest`
|
|
|
|
## Affected Artifacts
|
|
|
|
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsDeclarationSemanticsValidator.java`
|
|
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsDeclarationRuleValidator.java`
|
|
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsSemanticsErrors.java`
|
|
- PBS semantics tests
|