Guides
API docs
Last updated November 2, 2026
A package page has an API tab. It lists the classes, functions, properties, and types of the open version. Your browser reads them from the doc comments and the code in the package's source, so every published version has the tab. You publish nothing extra for it.
Your browser downloads the source only when you open the tab, and the Source tab then uses the same copy. When the source holds no API, such as in a package that only prints, the tab says "No API found in this version."
What the tab shows#
- A list of classes. On a wide screen the list is a sidebar. On a phone it is a menu above the class.
- Each class with its description, its types, its properties, and its functions.
- Each function with its signature as the code writes it, a table of
its parameters, its return values, the errors it can raise, and a badge
for each tag, such as
deprecated,yields,server, orclient.
Every item has an anchor, such as #Signal.Connect. A link to
/package/<scope>/<name>?tab=api#Signal.Connect opens the tab at that
function.
The doc comment format#
The format is the one Moonwave reads. Many Wally packages already use it, so their docs show with no change. A doc comment is one of these:
- A block comment with at least one
=in its brackets:--[=[ ... ]=]. - A run of lines that start with
---, with no blank line between them.
A plain -- or --[[ ]] comment is not a doc comment. In a doc comment, a
line that starts with @ is a tag, and a line that starts with . is a
field of an interface. All other lines are the description, in Markdown.
--[=[
@class Signal
A Signal fires events. Connect a handler with [Signal:Connect].
]=]
local Signal = {}
Signal.__index = Signal
--[=[
@within Signal
@interface Connection
.Connected boolean -- True until you disconnect
.Disconnect (self: Connection) -> ()
]=]
--[=[
Connects a function to the signal.
@param handler (...any) -> () -- Called on each fire
@return Connection -- The link to the handler
]=]
function Signal:Connect(handler)
end
--- The arguments that a handler gets.
export type Args = { any }
When a doc comment has no kind tag, Ember reads the statement below it:
function A.b(...)is a functionbof the classA.function A:b(...)is a methodbofA.A.b = function(...)is a functionbofA.export type X = ...is a type of the file's class.
The signature comes from the code, generics and return type included. A
parameter without a @param tag gets its type from the annotation. A
@param tag with no type keeps the annotation's type. A function with no
@return tag shows its return annotation.
[Name], [Class.member], and [Class:method] in a description link to
that item. A :::note block, or one of any other kind, shows as a quote
with a label.
Tags#
| Tag | Use |
|---|---|
@class Name | Starts a class. Its comment is the class description. |
@within Name | Puts an item in a class. A function on a table gets the table's name with no tag. |
@function name | A function that the code below does not define. |
@method name | A method that the code below does not define. |
@prop name type | A property. |
@type name type | A type. |
@interface Name | A table type. Write its fields as .name type -- description lines or @field tags. |
@param name type -- description | A parameter. The type is optional. |
@return type -- description | A return value. Write one tag for each value. |
@error type -- description | An error that the function can raise. |
@yields | The function yields. |
@tag name | A badge of your own. |
@since version | The version that added the item. |
@deprecated version -- description | The item is deprecated. The description says what to use. |
@private | Hidden until the visitor checks Show private. |
@ignore | Never shown. |
@readonly | A property that you must not set. |
@server, @client, @plugin | Where the item runs. You can use more than one. |
@unreleased | The item is not in a release yet. |
@external Name url | A type from another project. That type name links to the URL. |
@__index name | The table that holds the class's methods, when it is not __index. @index works too. |
An unknown tag, or an @within that names a class with no @class, adds a
note at the bottom of the tab. The note gives the file and the line, so you
can find the comment to fix.
Ember does not read these files: files in a packages or Packages folder,
test files (*.spec.*, *.test.*, __tests__, tests), and the Alloy
runtime, alloy.luau, of an Alloy package.
Packages with no doc comments#
When the source has no doc comments that make an API, the tab shows the
entry module's surface. The entry is the main file of
[target]. The tab shows:
- Each
function X.y,function X:y, andX.y = functionon the tableXthat the module returns, with its signature. - Each
export typein the module, with its definition. - The plain
--comment lines right above an item, as its description.
When the module returns a table of requires, such as
return { fs = require("@self/fs") }, each of those modules is a class of
its own. The tab then says that it shows the module's functions and types,
and not doc comments.