---
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