bQUARKz
725c28b3f5
All checks were successful
JaCoCo Coverage #### Project Overview
No changes detected, that affect the code coverage.
* Line Coverage: 61.37% (17351/28272)
* Branch Coverage: 52.31% (6722/12850)
* Lines of Code: 28272
* Cyclomatic Complexity: 11325
#### Quality Gates Summary
Output truncated.
Test / Build skipped: 15, passed: 601
Intrepid/Prometeu/Studio/pipeline/pr-master This commit looks good
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
74 lines
2.9 KiB
Markdown
74 lines
2.9 KiB
Markdown
---
|
|
id: PLN-0102
|
|
ticket: pbs-symbol-documentation-and-hover-markdown
|
|
title: Add end-to-end Doc documentation conformance coverage
|
|
status: done
|
|
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.
|
|
|
|
## Manual VSCode Validation Checklist
|
|
|
|
This plan intentionally does not automate VSCode UI rendering. Before final housekeeping, validate manually that:
|
|
|
|
- hover renders a `Doc` paragraph below the symbol signature and kind;
|
|
- Markdown lists render from `- item` documentation lines;
|
|
- code spans such as `` `color` `` render as inline code;
|
|
- normalized indentation from `[Doc(markdown = """...""")]` does not leak leading source indentation into hover;
|
|
- undocumented symbols still show the existing hover fallback without an empty documentation block;
|
|
- completion documentation matches the same Markdown payload used by hover.
|
|
|
|
## 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
|