Section 16: Documentation and AI Discoverability¶

TECHSPEC-16 — Section 16 · Version 0.1 · Status: Initial Draft

Status: draft. This section is an Initial Draft (Section 57 is a Working Register). It describes intended or proposed behavior, not a finalized, implemented language rule. Do not treat examples here as normative.

1. Documentation Philosophy¶

Documentation is part of the language specification, not an optional supplement.

Every language feature, standard library API, compiler diagnostic, and verification rule must have authoritative documentation.

Documentation must describe actual language behavior rather than intended or assumed behavior.

2. Language Specification¶

The language must maintain a formal, versioned specification.

It must document: - Syntax and grammar. - Type rules. - Function and contract semantics. - Control flow. - Variable and state behavior. - Ownership and borrowing. - Concurrency. - Effects and permissions. - Error handling. - Verification rules. - Runtime behavior. - Compiler requirements.

Rules: - Every released language version must have a corresponding specification. - Changes to language behavior must be documented. - Ambiguous rules must be resolved before being treated as normative. - Examples must follow the actual specification. - Historical specifications must remain accessible.

3. Machine-Readable Documentation¶

Documentation must be available in formats AI agents can reliably process.

The system should provide structured metadata for: - Types. - Functions. - Parameters. - Return values. - Contracts. - Effects. - Permissions. - Possible failures. - Dependencies. - Verification evidence. - Compiler diagnostics.

Machine-readable documentation must be generated from or validated against authoritative declarations wherever practical.

4. API Documentation¶

Every public function and type must have documentation.

Function documentation must include: - Purpose. - Parameters. - Return type. - Preconditions. - Postconditions. - Side effects. - Required permissions. - Possible failures. - Resource behavior. - Verification status. - Known limitations.

Documentation must not claim guarantees that the implementation or available evidence does not support.

5. Compiler Documentation¶

Compiler diagnostics must reference the relevant language rule.

Documentation must explain: - What the diagnostic means. - Which rule was violated. - Why the compiler rejected the code. - What evidence triggered the diagnostic. - Which corrections may resolve the issue.

Suggested corrections must remain suggestions until independently checked.

6. AI Agent Discoverability¶

The language must provide a structured interface through which AI agents can inspect the language environment.

Agents should be able to query: - Available language features. - Type definitions. - Function signatures. - Contracts. - Effects and permissions. - Module interfaces. - Dependencies. - Compiler diagnostics. - Verification results. - Known limitations.

The interface must return structured information rather than requiring agents to infer important rules from prose examples.

7. Documentation Integrity¶

Documentation must remain synchronized with the language implementation.

Rules: - Examples must be compile-checked where practical. - API documentation must be checked against actual declarations. - Documentation changes must be versioned. - Outdated documentation must be identified. - Conflicts between documentation and implementation must be reported. - The formal language specification takes precedence over informal tutorials and examples.

8. Compiler and Tooling Responsibilities¶

The development tools must: - Expose documentation to AI agents. - Link diagnostics to specification rules. - Support structured API discovery. - Identify documentation version mismatches. - Validate documentation examples. - Preserve links between declarations and their documentation.

9. Design Goal¶

AI agents must be able to discover and understand the language's actual rules without relying on guesswork, outdated examples, or undocumented assumptions.

Documentation must be authoritative, versioned, machine-readable, and consistent with implemented behavior.

Source file: TECHSPEC-16.md (preserved in source-original/LANG/). See the specification index, the glossary, and the cross-reference index.