Formatter & Documentation

Relevant source files

The following files were used as context for generating this wiki page:

• architecture/20-xml-documentation-comments.md
• architecture/decisions/0057-multiline-xml-documentation-format.md
• architecture/decisions/0014-xml-documentation-comments.md
• crates/compiler/documentation/src/lib.rs
• crates/tools/formatter/tests/documentation.rs
• crates/compiler/documentation/tests/documentation.rs

Pop Lang implements a structured approach to code formatting and API documentation, utilizing checked XML fragments embedded within Lua-style triple-hyphen (---) comments. Documentation in Pop is not merely an unparsed blob of text but a checked companion to declarations, integrated into the compiler pipeline to ensure semantic accuracy without the overhead of runtime reflection.

The system is designed to provide C#-style structured documentation while adhering to Pop’s Luau-inspired syntax. It enforces strict multiline formatting rules to ensure consistency and readability across the standard library and user projects.

Documentation Architecture & Syntax

Documentation comments in Pop use the --- delimiter. Consecutive lines starting with --- form a single XML fragment that attaches to the immediately following declaration. Attachment can be broken by blank lines, unrelated tokens, or ordinary comments (--).

Documentation Pipeline

The compiler processes documentation through several distinct stages, from lexical analysis to semantic validation.

The documentation system is purely a compile-time construct; cref resolution results in stable DocId values rather than runtime strings.
Sources: architecture/20-xml-documentation-comments.md:12-25, architecture/20-xml-documentation-comments.md:209-220

Key Documentation Tags

Pop adapts standard C# XML tags and introduces specific contract tags for performance and safety.

Tag	Purpose	Validation Rules
<summary>	Concise API description	Required for public declarations; no duplicates.
<param>	Documents value parameters	Name must exist in signature; no duplicates.
<returns>	Documents successful return	Required if function returns a value; restricted to Result.Ok for results.
<error>	Documents typed error cases	type must resolve to a valid nominal error or case.
<panic>	Documents invariant failure	Purely descriptive; documents conditions under which a panic occurs.
<effect>	Tracks side effects	Kinds (e.g., Blocks, Allocates) checked against effect analysis.
<complexity>	Tracks performance bounds	Declares time and space complexity (e.g., O(n log n)).
<inheritdoc>	Reuses parent documentation	Resolves source symbol; checks for cycles.

Sources: architecture/20-xml-documentation-comments.md:73-98, architecture/20-xml-documentation-comments.md:112-145

Canonical Multiline Formatting (ADR 0057)

To ensure a predictable source shape and easier diffing, Pop Lang enforces a strict multiline formatting rule for documentation elements.

Formatting Rules

1. Tag Separation: Every non-empty XML element must place its opening tag, body content, and closing tag on separate documentation lines.
2. Sibling Separation: Top-level contract elements (e.g., between <summary> and <param>) must be separated by exactly one empty documentation line (---).
3. Self-Closing Elements: Genuinely empty elements (e.g., <inheritdoc/>) may retain their self-closing form on a single line.
4. Whitespace: The formatter removes one optional space after the --- delimiter but preserves whitespace within <code> blocks.

--- <summary>
--- Divides one integer by another.
--- </summary>
---
--- <param name="divisor">
--- The divisor.
--- </param>
public function divide(value: Int, divisor: Int): Int
end

Sources: architecture/decisions/0057-multiline-xml-documentation-format.md:15-38, crates/tools/formatter/tests/documentation.rs:25-78

Semantic Validation and Diagnostics

The DocumentationAnalysis component provides a suite of checks to ensure that documentation remains in sync with the actual code.

Validator Responsibilities

Documentation Diagnostics (POP64xx–POP65xx)

Pop emits structured diagnostics for documentation errors. These are typically warnings by default to allow compilation to proceed.

• POP6400: Unsafe XML constructs (e.g., DTDs, external entities).
• POP6401: Malformed XML fragments (e.g., mismatched tags).
• POP6402: Invalid <error> tag (resolves to an incorrect type or case).
• POP6403: Missing error case documentation in a public contract.
• POP6408: Invalid <returns> tag (e.g., documented on a Void function).

Sources: architecture/20-xml-documentation-comments.md:238-255, crates/compiler/documentation/tests/documentation.rs:135-155, crates/compiler/documentation/tests/documentation.rs:200-220

Security and XML Handling

The XML parser is intentionally restricted to prevent security vulnerabilities such as "Billion Laughs" attacks or unauthorized filesystem access during the documentation build.

Security Restrictions

• No External Entities: DTDs, external entity declarations, and XInclude are forbidden.
• Budgeted Parsing: Parser depth, attribute counts, and text sizes are strictly budgeted to prevent resource exhaustion.
• Safe Entities: Expansion is limited to predefined XML entities (&, <, >, ", ').
• No Evaluation: CDATA and text content are never parsed as Pop source or "string mixins" unless specifically targeted by a documentation test runner.

Sources: architecture/20-xml-documentation-comments.md:175-188, crates/compiler/documentation/src/lib.rs:488-510

Conclusion

The Pop Lang Formatter & Documentation system establishes a high bar for API clarity by treating documentation as a semantically validated part of the codebase. By combining a strict multiline formatting standard (ADR 0057) with comprehensive compiler-level checks for errors, effects, and returns, Pop ensures that its standard library and external packages remain reliable and well-documented. This architecture allows for rich editor integration and high-quality generated artifacts without incurring runtime costs.