63 lines
2.3 KiB
Markdown
63 lines
2.3 KiB
Markdown
---
|
|
id: PLN-0102
|
|
ticket: pbs-symbol-documentation-and-hover-markdown
|
|
title: Add end-to-end Doc documentation conformance coverage
|
|
status: open
|
|
created: 2026-07-15
|
|
ref_decisions: [DEC-0039]
|
|
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
Close the feature with end-to-end tests that prove the whole `[Doc]` contract works across compiler and LSP boundaries.
|
|
|
|
## Objective
|
|
|
|
Validate that syntax, normalization, semantics, metadata attachment, LSP exposure, hover composition, stdlib docs, and runtime exclusion all satisfy `DEC-0039`.
|
|
|
|
## Dependencies
|
|
|
|
- Depends on `PLN-0092` through `PLN-0101`.
|
|
|
|
## Scope
|
|
|
|
- Add integrated compiler tests for valid and invalid `[Doc]`.
|
|
- Add LSP tests for hover documentation payloads.
|
|
- Add conformance coverage for normalization and runtime exclusion.
|
|
- Define a manual VSCode checklist for final visual validation.
|
|
|
|
## Non-Goals
|
|
|
|
- Automate VSCode UI rendering.
|
|
- Add new documentation syntax beyond `[Doc(markdown = """...""")]`.
|
|
- Reopen decision scope.
|
|
|
|
## Execution Method
|
|
|
|
1. Create one or more fixture PBS files using `[Doc]` on functions, methods, structs/classes when available, services, hosts, and interface declarations.
|
|
2. Add negative fixtures for parameters, duplicate `Doc`, empty payload, missing `markdown`, extra arguments, alias names, and invalid targets.
|
|
3. Add LSP tests proving hover transports Markdown and does not reparse source.
|
|
4. Add runtime artifact tests proving docs do not lower.
|
|
5. Record a short manual VSCode validation checklist covering paragraph rendering, list rendering, code spans, indentation behavior, and undocumented-symbol fallback.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- All decision rules have at least one compiler or LSP test.
|
|
- Manual VSCode validation scope is documented but not automated.
|
|
- The feature can be implemented without returning to the agenda or decision for missing requirements.
|
|
|
|
## Tests
|
|
|
|
- Full relevant PBS frontend test suite.
|
|
- Relevant LSP module tests.
|
|
- Runtime/lowering golden tests.
|
|
- Manual VSCode checklist execution before final housekeeping.
|
|
|
|
## Affected Artifacts
|
|
|
|
- PBS frontend tests and fixtures
|
|
- LSP tests and fixtures
|
|
- Golden/runtime artifact tests
|
|
- Optional manual validation note in the implementation PR or plan completion record
|