---
id: PLN-0095
ticket: pbs-symbol-documentation-and-hover-markdown
title: Implement documentation text block normalization
status: done
created: 2026-07-15
ref_decisions: [DEC-0039]
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
---

## Briefing

Implement the normalization algorithm required before semantic validation and editor exposure.

## Objective

Produce normalized Markdown text from a raw documentation text block using the rules locked by `DEC-0039`.

## Dependencies

- Depends on `PLN-0092`.
- Depends on `PLN-0094` for AST access to raw text block payloads.

## Scope

- Strip incidental leading and trailing empty lines.
- Compute and remove common indentation from non-empty lines.
- Preserve internal line breaks and Markdown content after normalization.
- Provide a single reusable normalization implementation for parser/semantics/editorial surfaces.

## Non-Goals

- Render Markdown.
- Sanitize Markdown for a specific editor.
- Reflow authored text.

## Execution Method

1. Add a small normalization helper in the PBS frontend package, colocated with parser or semantic support according to local patterns.
2. Feed the helper raw documentation text block content without delimiters.
3. Normalize line endings deterministically before indentation calculation if existing source handling requires it.
4. Validate empty/whitespace-only content after normalization.
5. Add unit tests for no indentation, common indentation, blank first/last lines, mixed blank internal lines, Markdown lists, code spans, and whitespace-only payloads.

## Acceptance Criteria

- Normalized output matches the spec for all required indentation cases.
- Whitespace-only content is detectable after normalization.
- The normalizer does not interpret Markdown and does not alter non-indentation content.

## Tests

- New focused unit tests for the normalizer.
- Parser/semantic tests that consume normalized output through `[Doc]`.

## Affected Artifacts

- New or existing PBS frontend helper under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs`
- Corresponding tests under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs`