Skip to content

v0.3.0

Choose a tag to compare

@github-actions github-actions released this 15 Oct 03:58
· 23 commits to main since this release
v0.3.0
00aa8ba

Added

  • Classes defined separately from their constructor table are documented.
    Typed Luau libraries often keep methods on a local self-indexing table that
    the module never returns (local Deque = {}, Deque.__index = Deque,
    function Deque.pushback(self: Deque<T>, value: T)) and return a table
    containing only new, which attaches Deque via setmetatable(_, Deque).
    The extractor now follows that attachment (or a type that declares it via
    typeof(setmetatable(_, Deque)) or setmetatable<_, typeof(Deque)>; bare
    setmetatable<D, M> is not recognized as a class type) and documents the
    table as a class named after the type (or the local variable when no type
    names it), with the constructor grouped under the class.
    Self-indexing (T.__index = T) alone still does not make a table a class:
    the setmetatable attachment is what distinguishes a class from a
    self-indexing module namespace.
  • Requires of runtime modules are treated as external rather than unresolved.
    Requiring a module through a runtime-supplied alias (@lute/fs, @std/path,
    @lune/net) rather than .luaurc no longer emits require-unresolved on
    every build. Lute and Lune aliases are built in, and [source.aliases] lets
    you register custom runtime aliases or override built-in ones with a
    documentation base URL. Mounting a runtime module renders as a property
    showing the require(...) call and linking to its documentation URL, and
    types referenced through a runtime alias (fs.File) link to that module's
    page just like Roblox types link to Creator Documentation. A .luaurc alias
    of the same name still takes precedence. In the doc model, Reexport gained
    an optional url field for runtime mounts, and externals values are now
    either the URL string declared by @external or an object
    { url?, alias, path, name? } for types reached through a runtime alias.
  • Sites can cross-link to each other's symbols. Setting [docs] model = true
    publishes the doc model at public/docmodel.json, and configuring a
    [source.aliases] entry as { url, model } loads that external doc model so
    types reached through the alias link directly to their exact #anchor on the
    external site rather than only to the module page. model accepts either an
    http(s):// URL (fetched and cached per user, with the cache used as a
    fallback when offline) or a project-relative file path; an unreadable model
    emits a warning and falls back to module-level links. Existing sites should
    add /public/docmodel.json to their docs directory's .gitignore (newly
    scaffolded sites include it automatically).
  • [api] reportUndocumented gates documentation coverage. When enabled, it
    emits an undocumented warning for every public member, class, and exported
    type without a doc comment, formatted as callers write it (Widget:refresh),
    so luaudocs build --strict fails until the public surface is fully
    documented. Disabled by default.
  • Exported types in tags-only modules are reported instead of silently dropped.
    When a module is required only for its types (for example, local types = require("./types"))
    and never mounted on the public surface, its unreached exported types now emit
    an unreached-types info diagnostic naming the types and the two ways to
    surface them (export type Name = ... in a public module or @within on the
    declaration). Types already re-exported by a surfaced module
    (export type Hook = types.Hook) are excluded.
  • function T.f(self: T, ...) documents as a method. Explicitly typing
    self as the first parameter of a dot-defined function (which Luau's :
    syntax cannot annotate) now renders with : syntax (T:f(...)) and omits
    self from the parameter list, and a single such method is enough to classify
    T as a class. Adding @function still forces it to render as a dot
    function with self kept in the signature.
  • Lazy module loaders, typeof(require(...)) mounts, and __index delegation.
    Functions whose body is return require(X) follow X in the module graph and
    infer X as their linked return type when unannotated or annotated
    typeof(require(X)). Table fields declared as Key: typeof(require(...)) on
    a returned table's type annotation synthesize module mounts, and
    setmetatable(M, { __index = Proto }) delegates fields from Proto (including
    when Proto comes from a local factory call).
  • Container type annotation fallback and expanded re-exported types.
    Unannotated properties (or properties cast to :: any) fall back to the field's
    type and doc comment on the owning table's type annotation, and re-exported
    type aliases (export type T = Other.T or export type T<U> = Other.T<U>)
    expand the origin type's underlying definition, generics, fields, and fallback
    doc comment.
  • luaudocs llms generates a project-root llms.txt for coding agents.
    While the site's /llms.txt serves AI tools browsing your deployed docs,
    luaudocs llms writes a compact llms.txt at the repository root for coding
    agents working in a local checkout (referenced from AGENTS.md or
    CLAUDE.md). It indexes your guide files followed by one section per module,
    headed by the require(...) expression that reaches the module and listing
    its types and members as Luau signatures linked to their file:line
    declarations. It requires no luaudocs init or VitePress build and reads only
    committed repository files; its header instructs agents to rerun
    npx luaudocs@<version> llms after changing the public API, doc comments, or
    guides. Pass --check in CI to fail on a missing or stale llms.txt, or
    --out <file> to write to another path. LuauDocs refuses to overwrite an
    llms.txt that does not carry its generated marker, and aborts without
    writing when extraction produces an error. See
    Coding Agents.
  • Cloudflare Pages deployment guide.
    Deploying now
    documents building and hosting directly on Cloudflare Pages without a GitHub
    Actions workflow file.

Changed

  • Documentation site moved to
    luaudocs.pages.dev.
    luaudocs.kohl.gg
    redirects to the new domain, and package metadata plus newly scaffolded
    starter guides now link to luaudocs.pages.dev.
  • Stricter configuration validation for paths and URLs. Setting [docs] dir
    at or outside the project root (".", "..", "../site", or /abs/path)
    is now rejected so a build can never overwrite the project's own
    package.json or CHANGELOG.md. URL fields and --url must use http://
    or https://, preventing host-only strings (docs.example.com:8080) from
    being parsed as URL schemes and preventing ssh:// repo URLs from generating
    unclickable source links. [docs] dir is also normalized to clean POSIX
    form so ./docs/ no longer leaks leading ./ or trailing slashes into edit
    links and the GitHub Pages workflow.
  • init validates existing luaudocs.toml files and probes conventional source roots.
    luaudocs init now fails fast on an invalid luaudocs.toml instead of
    falling back to default settings, and scaffolds [source] entries from the
    existing conventional directories (src/, lib/) so projects using lib/
    build out of the box.
  • The scaffolded GitHub Pages workflow caches ~/.cache/luaudocs alongside
    npm and node_modules so CI runs reuse the downloaded Lute binary.
  • VitePress build failures exit with code 1 (build failure) rather than
    2 (usage/config error).
  • Constructor detection requires a bare class return type (with optional
    generic arguments): functions returning Widget?, { Widget }, or
    Promise<Widget> are no longer classified as constructors of Widget.
  • Root functions that re-expose an implicit class's constructor or method
    (return { new = Signal.new }) are documented once on the class rather than
    duplicated on the module root.
  • Internal contracts updated in place: Reexport in the doc model gained
    optional realm and within fields; the generated API sidebar navigation
    moved to .vitepress/generated/api-nav.ts; and generated changelog.md
    files now include the # Generated by luaudocs ownership marker.

Fixed

  • Conditional module mounts written M.Server = RunService:IsServer() and require(...)
    now document the mounted module and attach its realm badge instead of
    rendering as an untyped property.
  • Re-exports inside nested containers now render on the nested class section
    rather than the module root, and member imports targeting an undocumented
    symbol fall back to rendering as a property alongside the
    unresolved-reexport diagnostic.
  • Modules promoted to a page solely by a @class tag now also surface the
    submodules they mount.
  • Block doc comments with text on the opening delimiter line (--[=[ Summary.)
    now dedent their body lines properly instead of treating indented @param
    tags as indented code blocks.
  • @return type overrides now update the rendered function signature just like
    @param types, and merging a standalone @function tag stub into a source
    function preserves the stub's @return entries and warns on unmatched
    @param or @return tags.
  • @prop and @readonly tags on a table-valued field keep it documented as a
    property rather than promoting it to a nested class, and @class,
    @function, @prop, or @method blocks placed directly above a type
    declaration are no longer consumed as the type alias's doc comment.
  • unreached-types no longer reports types that were moved to a surfaced class
    via @within, and unexported local type aliases are omitted when an
    @within-relocated exported type already owns that name on the page.
  • Duplicate member declarations that resolve to the same symbol ID now emit a
    duplicate-member warning instead of silently overwriting the earlier entry.
  • .luaurc files containing -- comments, // comments, or trailing commas
    now parse cleanly, matching Luau's own Config.cpp reader.
  • require(script.Parent.X) now resolves from an init.luau file whose Rojo
    $path mounts the file directly rather than its directory, relative string
    requires (require("./Sub"), require("@self/Sub")) fall back to the Rojo
    project tree when no sibling file matches on disk, and surfaced requires that
    resolve to a Folder or non-module instance path (script.Parent.Assets) emit
    require-nonmodule.
  • parse-error diagnostics now report 1-based line and column numbers and
    strip Lute's internal @std/syntax/parser.luau prefix.
  • Parallel assignments (a, b = b, a) now evaluate all right-hand expressions
    before updating any left-hand bindings.
  • Multi-line block comments inside inline type annotations are now stripped
    completely instead of leaving their closing lines in the signature.
  • Inline code spans containing {{ are escaped so Vue does not evaluate them
    as template interpolations.
  • Re-export badge links and linked <Frame> captions now prefix internal paths
    with VitePress's withBase so sites deployed under a subpath ([docs] url
    with a path prefix) do not 404.
  • Methods re-exported as plain fields (connect = Signal.Connect) now include
    the explicit self parameter required by dot-call syntax.
  • Member anchor predictions stay aligned with VitePress when a guide or doc
    comment contains headings with inline HTML, :emoji: shortcodes, reference
    links, custom {#id} suffixes, or list prefixes.
  • [Outer.Inner] doc-comment references now resolve to nested classes, nested
    classes no longer shadow a top-level module page of the same short name in
    [Reference] links, and [Ref] links inside @error descriptions are now
    resolved.
  • Nested classes with no public members or description no longer render an
    empty heading, and class names wrapped in underscores (_Inner_) are escaped
    so Markdown does not italicize them.
  • Linked union types preserve spaces around |, and source links or external
    type URLs containing spaces or parentheses are percent-encoded.
  • Roblox Enum.X types now link to Creator Documentation.
  • Guide pages added while an extraction error is active still appear in the
    sidebar; only the API navigation is frozen until the error is fixed.
  • Generated changelog.md files checked out with CRLF line endings are still
    recognized as tool-generated and cleaned up when [docs] changelog = false.
  • Concurrent first-time Lute downloads stage into process-specific temporary
    files and write installation notices to stderr, keeping stdout clean when
    piping extractor JSON.
  • Stopping luaudocs dev during initial VitePress dependency installation no
    longer spawns the dev server afterward.