Tealdoc Documentation

How to Document Your Code

Tealdoc Comments

Documentation can be written in special comments that begin with three hyphens (---).

--- This is a Tealdoc summary line.
--- The rest of the comment forms the detailed description.
--- It can span multiple lines.

---
-- This is also a valid Tealdoc comment.

You can also use a block comment.

--[[--
    This is a Tealdoc block comment.
    ...
]]--

Anatomy of a Comment

All documentation comments start with a brief summary sentence that ends with a period. The text that follows the summary becomes the detailed description.

After the description, you can add tags, which start with an @. Tags may optionally include a parameter and a description.

--- This is the summary. This is the detailed description.
-- @tag_name parameter The description for this tag.
-- @another_tag

Functions

Document functions by placing a Tealdoc comment directly above them. Parameter and return types are inferred automatically from the function's type annotations.

--- Adds two integers.
-- This function adds two integers together.
-- @param a The first integer to add.
-- @param b The second integer to add.
-- @return The sum of the two integers.
function test.foo(a: integer, b: integer): integer
    return a + b
end

You can use multiple @return tags to document functions with multiple return values:

--- Fetches messages from the server.
-- @return A table of messages if successful.
-- @return An error message on failure.
function client.fetch_messages(): {Message}, string
    ...
end

Use the @typearg tag to document generic type variables:

--[[--
    Calculates the area of a shape.
    @typearg S The type of the shape, which must implement `Shape`.
    @param shape The shape object.
    @return The area of the shape.
]]
local function area<S is Shape>(shape: S): number
    ...
end

Records and Interfaces

You can document records, interfaces, and all of their fields and nested types.

--- An abstract representation of a shape.
interface Shape
    --- The result type of any geometric calculation.
    --- Either a `double` value or an error string.
    type calculation_result = double | string

    --- The number of sides.
    sides: integer
end

--- A square shape.
record Square is Shape
    --- The length of the square's side in cm.
    side_length: double

    --- Calculates the square's diagonal.
    --- @return The diagonal length in cm.
    get_diagonal: function(shape): calculation_result
end

Functions can also be documented where they are defined, if outside the initial record definition:

--- Multiplies the length of all sides of the square.
-- @param x The factor to multiply by.
function Square:multiply_sides(x: number)
    ...
end

Note: If a function has documentation at both its declaration (inside the record) and its definition, the definition's documentation will be prioritized, and a warning will be emitted.

Enums

Enum types and their values can be documented:

--- Classifies a triangle by its side lengths.
enum TriangleType
    --- All sides are equal.
    "equilateral"
    --- Two sides are equal.
    "isosceles"
    --- No sides are equal.
    "scalene"
end

Variables and Types

You can also document variables and type declarations:

--- The mathematical constant PI, rounded to two decimal places.
global PI = 3.14

--- A type alias for a numeric value.
local type Numeric = number | integer

Controlling Visibility

By default, Tealdoc includes all of the module's contents and all global functions in the generated documentation.

To exclude an item, add the @local tag to its documentation comment.
To include local items that would normally be excluded, use the --all command-line flag or set env.include_all = true when using the API.

If there are multiple conflicting declarations (e.g., two global functions with the same name), the last one processed is chosen, and a warning is emitted if a Tealdoc comment from a previous declaration is ignored as a result.