Home › Reference
Tags
Every tag corrects or extends what the extractor already inferred, and none of them is ever required. Overriding with Tags covers the ones that come up in practice; the 23 tags listed below, plus @__index, form the complete vocabulary. The tables group them by shape: flags take no argument, placement tags declare what a block documents, and data tags carry values and descriptions.
Prose can sit before or after the tags. A -- desc (a single - works too) continues onto the lines directly below it until a blank line; after that, and after any tag that takes no description, prose rejoins the item's own description.
Flags
These take no argument. Most add a badge; two change whether the item is documented at all.
| Tag | Effect |
|---|---|
@yields | Yields the function may yield the calling thread. |
@unreleased | Unreleased |
@server | Server |
@client | Client |
@plugin | Plugin |
@readonly | Read Only on a property. |
@private | Private even without a _ prefix. |
@ignore | Drops the item from the docs entirely. |
@server, @client, and @plugin combine and render in that order. The Yields and realm badges are also detected from what a body does, and a prop renders Read Only when its table is table.freezed or its field is marked read in the table's own type (not one imported from another module), so these flags are only needed when the signal is not in the code (live: a Yields badge with no tag behind it). A realm tag replaces the detected realm, so the tag wins when they disagree.
The last two rows differ: @private keeps the member and renders it when [api] includePrivate = true, while @ignore drops it either way. Without either tag, a leading _ means private, except on an export type or a __-named function (a documented metamethod).
Placement
These declare what a block documents when inference cannot reach it, or when you want a member filed under a different class.
| Tag | Effect |
|---|---|
@class Name | Documents the block as a class named Name. |
@prop Name Type -- desc | Documents a property. @prop Class.name also files it under Class. |
@type Name Type -- desc | Documents a type declaration. |
@function Name | Documents a function. @function Class.name files it under Class. |
@method Name | Documents a method. @method Class:name is the colon spelling of the same. |
@interface Name | Documents a shape, with its members written as .field Type -- desc lines, blank lines between groups included. |
WARNING
A second placement tag in one block is a conflict: the first wins, the later one is reported and dropped.
Data
| Tag | Effect |
|---|---|
@param name Type -- desc | Documents one parameter. The type is optional; the signature already has it. |
@return Type -- desc | Documents one return value, in order. |
@error Type -- desc | Documents an error the function can raise. |
@field name Type -- desc | Documents one field of an @interface or of a type declaration. |
@within Class | Files the item under Class, wherever it is defined. |
@deprecated v2 -- use X | Deprecated since v2 plus a warning callout (live). Both parts are optional. |
@since 1.2.0 | since 1.2.0 (live) |
@tag name | name a badge carrying the tag's name. |
@external Name URL | Points an unresolvable type name at its own docs site. |
@param is also unnecessary in a multi-line signature, where a trailing -- comment on a parameter's line documents it; when both exist the tag wins field by field, so a type-only @param keeps the trailing description.
@external is the one tag that affects the whole site rather than the item it sits on: declared once, in any module, that name links wherever it appears in a signature or a [bracket] reference.
Type names written in tags
A type you name in a tag (@prop x Widget, @return Widget, a .field Widget line) links to what it names in the module where you wrote the tag: a type that module declares, or a class or module it requires. Any standard require syntax is supported: a module accessed through a table field links just as reliably as one bound to a local variable:
local _K = {
Flux = require(script.Flux), -- no local binding, and `.Flux Flux` still links
}A name the module never reaches stays unlinked rather than being matched against an unrelated module that happens to spell it the same way. Point one somewhere anyway with @external, or qualify it through a require-local (Util.Logger).
Tags that do nothing
@__index is accepted and ignored, since implementation tables are discovered automatically. It exists for Moonwave compatibility.
Unknown @words (credits, email addresses) stay in your prose untouched.