Home

Writing Doc Comments

Because LuauDocs discovers your exports, signatures, and types from source code, doc comments only need to explain what an item does.

The three styles

Place a comment block above a definition. All three comment styles work the same way:

Block

--[[
Creates a state holding `initial`.
See [State:Connect] for reacting to changes.
]]
function Flux.state<T>(initial: T?): State.State<T>

Triple dash

--- Creates a state holding `initial`.
--- See [State:Connect] for reacting to changes.
function Flux.state<T>(initial: T?): State.State<T>

Long bracket

--[=[
Creates a state holding `initial`.
Prose here can contain [[ and ]] freely.
]=]
function Flux.state<T>(initial: T?): State.State<T>

Descriptions use Markdown (lists, links, fenced code, and emphasis), and tags are optional. Multiple paragraphs render as separate paragraphs:

examples/Flux/State.luau

--[[
Runs `callback` whenever the value changes.

Returns a function that disconnects the listener again.
]]
function State:Connect(callback: (any) -> ()): () -> ()

Generated reference→

Connect

State:Connect(callback: (any) -> ()): () -> ()

Runs callback whenever the value changes.

Returns a function that disconnects the listener again.

Documenting fields

Document table or type fields with either a preceding doc comment or a trailing comment on the same line:

export type Options = {
	--[[ How long to wait before giving up. ]]
	timeout: number,
	retries: number, -- how many attempts after the first
}

On a table-literal member, field prose renders as full Markdown, including references. On a type declaration, field descriptions render inside the type's Luau code fence as -- comment lines with inline formatting stripped, so keep type-field descriptions short.

Documenting the module itself

Place a doc comment above the returned table's definition (or at the top of the file before the first statement) to set the module page's opening prose:

--[[
A tiny reactive state library.
]]
local Flux = {}

That comment becomes the introduction on the Flux page. A @class block's description works the same way for tag-declared classes.

References that link themselves

Wrap a symbol name in square brackets to link it:

You write	It resolves to
[Class]	that class or module's page
[Class.member]	the member's anchor on that page
[Class:method]	the method's anchor on that page
[CFrame]	the Roblox Creator Documentation

Bare names resolve against your project first (with modules outranking same-named types), then @external declarations, and finally Roblox engine types. Dotted and colon forms resolve only within your project.

Unresolved brackets stay as plain [OldName] text instead of emitting broken links. If a reference is ambiguous (such as two modules named Defaults), LuauDocs leaves it unlinked and emits an ambiguous-ref warning. Qualify the reference ([Module.State]) to disambiguate it.

Rich markup

Doc comments support the same rich markup as guide pages, including admonitions, tab strips, frames, badges, and inline {luau} highlighting. See Overriding with Tags when you need to override inferred signatures or placement.