Declaring objects

Modules

.. lua:module:: name

Specifies beginning of a module. Other objects declared after this directive will be automatically attached to this module.

This directive doesn’t accept any content, it just creates an anchor.

Modules are something you can require. If you need to document a namespace inside of a module, use a lua:table instead.

.. lua:currentmodule:: name

Switches current module without making an index entry or an anchor. If name is None, sets current module to be the global namespace.

This directive can’t be used inside other lua objects.

Objects

.. lua:data:: name: type

.. lua:const:: name: type

.. lua:attribute:: name: type

Directives for documenting variables. Accepts name of the variable, and an optional type:

RST

.. lua:data:: name: string

   Person's name.

Markdown

```{lua:data} name: string
Person's name.
```

Example output

name: string

Person’s name.

Using type instead of a name is also supported:

RST

.. lua:data:: [integer]: string

   Array contents.

Markdown

```{lua:data} [integer]: string
Array contents.
```

Example output

[integer]: string

Array contents.

.. lua:table:: name

Directive for documenting tables that serve as namespaces. It works like lua:data, but can contain nested members.

.. lua:function:: name<generics>(param: type): type

.. lua:method:: name<generics>(param: type): type

.. lua:classmethod:: name<generics>(param: type): type

.. lua:staticmethod:: name<generics>(param: type): type

Directives for documenting functions and class methods:

RST

.. lua:function:: doABarrelRoll(times: integer): (success: boolean)

   Does a barrel roll given amount of times. Returns ``true`` if successful.

Markdown

```{lua:function} doABarrelRoll(times: integer): (success: boolean)
Does a barrel roll given amount of times. Returns ``true`` if successful.
```

Example output

doABarrelRoll(times: integer): (success: boolean)

Does a barrel roll given amount of times. Returns true if successful.

This directive can also document multiple function overloads at once:

RST

.. lua:function:: table.insert<T>(array: T[], item: T): integer
                  table.insert<T>(array: T[], index: integer, item: T): integer

   Insert a value into an array.

Markdown

```{eval-rst}
.. lua:function:: table.insert<T>(array: T[], item: T): integer
                  table.insert<T>(array: T[], index: integer, item: T): integer

   Insert a value into an array.
```

Note

MySt doesn’t support directives with multiple arguments, so we use eval-rst to bypass it.

Example output

table.insert<T>(array: T[], item: T): integer

table.insert<T>(array: T[], index: integer, item: T): integer

Insert a value into an array.

.. lua:class:: name<generics>: bases

.. lua:class:: name<generics>(param: type): type

For documenting classes and metatables:

RST

.. lua:class:: Logger: LogFilter, LogSink

   The user-facing interface for logging messages.

Markdown

```{lua:class} Logger: LogFilter, LogSink
The user-facing interface for logging messages.
```

Example output

class Logger: LogFilter, LogSink

The user-facing interface for logging messages.

This directive can also document constructors:

RST

.. lua:class:: Logger: LogFilter, LogSink
               Logger(level: LogLevel)

   The user-facing interface for logging messages.

Markdown

```{eval-rst}
.. lua:class:: Logger: LogFilter, LogSink
               Logger(level: LogLevel)

   The user-facing interface for logging messages.
```

Note

MySt doesn’t support directives with multiple arguments, so we use eval-rst to bypass it.

Example output

class Logger: LogFilter, LogSink

class ctor Logger(level: LogLevel)

The user-facing interface for logging messages.

.. lua:alias:: name<generics> = type

.. lua:enum:: name

For documenting type aliases and enums:

RST

.. lua:alias:: LogLevel = integer

   Verbosity level of a log message.

Markdown

```{lua:alias} LogLevel = integer
Verbosity level of a log message.
```

Example output

alias LogLevel = integer

Verbosity level of a log message.

Parameters

All directives that document Lua objects accept the standard parameters:

:no-index:

Render the documentation, but don’t add it to the index and don’t create anchors. You will not be able to reference un-indexed objects.

:private:

:protected:

:package:

:virtual:

:abstract:

:async:

:global:

Adds a corresponding annotation before object’s name:

RST

.. lua:function:: fetch(url: string): (code: integer, content: string?)
   :async:

   Fetches content from the given url.

Markdown

```{lua:function} fetch(url: string): (code: integer, content: string?)
:async:
Fetches content from the given url.
```

Example output

async fetch(url: string): (code: integer, content?: string)

Fetches content from the given url.

:annotation:

Allows adding custom short annotations.

:deprecated:

Marks object as deprecated in index and when cross-referencing. This will not add any text to the documented object, you’ll need to use the deprecated directive for this:

RST

.. lua:data:: fullname: string
   :deprecated:

   Person's full name.

   .. deprecated:: 3.2

      Use ``name`` and ``surname`` instead.

Markdown

````{lua:data} fullname: string
:deprecated:

Person's full name.

  ```{deprecated} 3.2
  Use ``name`` and ``surname`` instead.
  ```

````

Example output

fullname: string

Person’s full name.

Deprecated since version 3.2: Use name and surname instead.

:synopsis:

Allows adding a small description that’s reflected in the lua:autoindex output.

:module:

Allows overriding current module for a single object. This is useful for documenting global variables that are declared in a module.