slovo/.llm/BETA_11_LOCAL_PACKAGE_API_DOCUMENTATION.md

1.0.0-beta.11 Local Package API Documentation

Status: release scope for 1.0.0-beta.11.

1.0.0-beta.11 extends the beta.10 API discovery lane. The release keeps the 1.0.0-beta source-language and runtime baseline unchanged while making local package and module documentation show the public API surface users need to review.

Scope

• Extend glagol doc <file|project|workspace> -o <dir> so generated Markdown includes deterministic exported/public API sections for local source files, projects, packages, and workspaces.
• Render exact exported function signatures with parameter names, parameter types, and return types.
• Render exported struct field names and field types.
• Render exported enum variant names and payload types for payloadless and current single-payload variants.
• Keep non-exported functions, structs, enums, tests, and (type ...) aliases out of the public API sections.
• Normalize module-local concrete aliases before rendering public types, so private names such as VecI32, OptionString, or ResultU64 do not leak into local package/module public docs.
• Update README, language docs, compiler docs, and the post-beta roadmap to describe the beta11 documentation contract clearly.

Public Contract

The generated local documentation is a beta API discovery aid. It exposes what the current local module/package export lists make public, with concrete public types after alias normalization.

The public API sections are deterministic and suitable for human review, but they are not a stable machine-readable Markdown schema. Headings, anchors, file names, and surrounding prose remain beta-scoped unless a later release freezes them explicitly.

Explicit Non-Scope

• no stable Markdown schema
• no stable stdlib/API compatibility freeze
• no LSP server or watch mode
• no SARIF or daemon protocol
• no diagnostics schema policy
• no executable generics
• no maps or sets
• no re-exports, glob imports, or hierarchical modules
• no package registry semantics
• no new compiler-known runtime names
• no runtime helper or ABI/layout changes

Checks

Focused checks for this slice:

• git diff --check -- README.md docs/POST_BETA_ROADMAP.md docs/language/ROADMAP.md docs/language/RELEASE_NOTES.md docs/language/SPEC-v1.md docs/compiler/ROADMAP.md docs/compiler/RELEASE_NOTES.md .llm/BETA_11_LOCAL_PACKAGE_API_DOCUMENTATION.md