ember
Documentation menuembr 0.13.0

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, or client.

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 function b of the class A.
  • function A:b(...) is a method b of A.
  • A.b = function(...) is a function b of A.
  • 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#

TagUse
@class NameStarts a class. Its comment is the class description.
@within NamePuts an item in a class. A function on a table gets the table's name with no tag.
@function nameA function that the code below does not define.
@method nameA method that the code below does not define.
@prop name typeA property.
@type name typeA type.
@interface NameA table type. Write its fields as .name type -- description lines or @field tags.
@param name type -- descriptionA parameter. The type is optional.
@return type -- descriptionA return value. Write one tag for each value.
@error type -- descriptionAn error that the function can raise.
@yieldsThe function yields.
@tag nameA badge of your own.
@since versionThe version that added the item.
@deprecated version -- descriptionThe item is deprecated. The description says what to use.
@privateHidden until the visitor checks Show private.
@ignoreNever shown.
@readonlyA property that you must not set.
@server, @client, @pluginWhere the item runs. You can use more than one.
@unreleasedThe item is not in a release yet.
@external Name urlA type from another project. That type name links to the URL.
@__index nameThe 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, and X.y = function on the table X that the module returns, with its signature.
  • Each export type in 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.