Generating documentation for objects

You can automatically generate object descriptions based on Lua source code.

Depending on which language analyzer you use, documentation comments can be slightly different:

EmmyLua doesn’t need any specific annotations beyond the standard documentation comments.

When generating documentation for a module, Sphinx-LuaLs will include all module’s objects returned by require, as well as all types located in the same namespace.

That is, for module meow, it will list everything in the require("meow"), as well as all classes, aliases, and enums that have prefix meow.*.

Thus, a typical Lua module will look like this:

--- A module for meowing and purring.
local meow = {}

--- A function exported from a module.
function meow.meow() end

--- Another function exported from a module.
function meow.purr() end

--- This class will be included in the documentation
--- for module `meow` because it's located in the namespace `meow`.
---
--- @class meow.MeowingBackend

return meow

Tip

You don’t have to manually prefix names of all types. Use @namespace to indicate that all types in a module belong to a certain namespace:

--- @namespace meow

--- A module for meowing and purring.
local meow = {}

...

--- This class will appear in namespace `meow` even though
--- we didn't write its full path.
---
--- @class MeowingBackend

return meow

Note

By default, Sphinx-LuaLs will parse object comments as ReStructured Text, not as MarkDown. If you plan to use Markdown in code comments, install the MySt plugin for Sphinx and invoke lua:autoobject from a markdown file.

Tables are exported as data by default, meaning that their contents are not documented.

To enable documentation within a table, annotate is as a class. You can change how Sphinx-LuaLs infers its type by adding a !doctype comment.

Thus, a typical Lua module will look like this:

--- This is a module. Notice that we've declared it as a class
--- and added a `doctype`.
---
--- !doctype module
--- @class meow
local meow = {}

--- Nested namespaces should also be declared as classes.
---
--- !doctype table
--- @class meow.utils
meow.utils = {}

--- Other objects are documented as usual.
function meow.purr() end

--- This class will be included in the documentation
--- for module `meow` because it's located in the namespace `meow`.
---
--- @class meow.MeowingBackend

return meow

Note

By default, Sphinx-LuaLs will parse object comments as ReStructured Text, not as MarkDown. If you plan to use Markdown in code comments, install the MySt plugin for Sphinx and invoke include lua:autoobject from a markdown file.

Make sure to separate comment markers from documentation with a space. Otherwise, Sphinx-LuaLs will not be able to tell your comments apart from content automatically generated by Lua Language Server:

--- This is OK: separated by a space.
local x = 0;

---This is NOT OK: no separation.
local x = 0;

Warning

Currently, Lua Language Server does not export all available information.

  1. @see markers can sometimes be broken. We recommend using the seealso directive instead.

  2. @deprecated markers do not add any note to the documentation. We recommend providing an explicit message with the deprecated directive.

  3. @nodiscard and @operator markers are not exported.

  4. Export of aliases (@alias) is somewhat broken. Documentation for an alias is appended to every object that mentions it. While Sphinx-LuaLs tries its best to remove it, there’s no way to completely remedy this issue.

  5. Export of enums (@enum) is completely broken. We recommend using @alias instead:

    --- Instead of enums, we use aliases.
---
--- .. lua:data:: Debug
---
---    Document alias members in its body.
---
--- And so on...
---
--- @alias logging.LogLevel integer
LogLevel = {
   Debug = 1,
   -- ...
}

Autodoc directives

.. lua:autoobject:: name

Automatically generates documentation for the given object.

lua:autoobject supports same settings as other lua directives, as well as some additional ones:

:members: [<name>, ...]

If enabled, autodoc will also document object’s members. You can pass a list of comma-separated names to specify which members should be documented. Otherwise, this option will document all public non-special members which have a description.

:undoc-members: [<name>, ...]

Include undocumented members to the object’s description. By default, they are skipped even if members is passed.

Accepts a comma-separated list of names; if list is empty, adds all undoc members.

:private-members: [<name>, ...]
:protected-members: [<name>, ...]
:package-members: [<name>, ...]

Include non-public members to the object’s description.

Accepts a comma-separated list of names; if list is empty, adds all non-public members.

:special-members: [<name>, ...]

Include members whose names start with double underscore to the object’s description.

Accepts a comma-separated list of names; if list is empty, adds all special members.

:inherited-members: [<name>, ...]

For classes, include members inherited from base classes.

Accepts a comma-separated list of names; if list is empty, adds all inherited members.

:exclude-members: [<name>, ...]

A comma-separated list of members that should not be documented.

:globals: [<name>, ...]

Will include global variables declared in the corresponding module.

Accepts a comma-separated list of names; if list is empty, adds all global variables.

:class-doc-from: class | ctor | both | separate

Specifies how to generate documentation for classes if lua_ls_class_default_function_name is configured.

Options are:

  • class: only use documentation from @class annotation,

  • ctor: only use documentation from class constructor,

  • both: use documentation from @class annotation and constructor, place them one next to another.

  • separate: only use documentation from @class annotation, document class constructor as a separate method.

:class-signature: bases | ctor | both | minimal

Specifies how to generate signatures for classes if lua_ls_class_default_function_name is configured.

Options are:

  • bases: only show base classes,

  • ctor: only show constructor arguments,

  • both: show base classes and constructor arguments,

  • minimal: show bases and/or constructor arguments if either is present.

Example

Bases:

class logging.Logger

An object for logging messages.

Ctor:

class ctor logging.Logger(name: string, level?: logging.Level)

An object for logging messages.

Both:

class logging.Logger
class ctor logging.Logger(name: string, level?: logging.Level)

An object for logging messages.

Minimal:

class ctor logging.Logger(name: string, level?: logging.Level)

An object for logging messages.

:recursive:

If enabled, autodoc will recursively generate documentation for all objects nested within the root. That is, object’s members, their members, and so on.

Options like no-index or lua:autoobject:member-order are always passed down to all members.

List options like lua:autoobject:members or lua:autoobject:globals are passed down if they’re empty or start with + (see lua_ls_default_options for info on + and overriding defaults).

:member-order: alphabetical | groupwise | bysource

Controls how members are sorted. There are three options available:

  • alphabetical: members are sorted in lexicographical order of their names;

  • groupwise: members are grouped by their type. Within each group, they are ordered by name;

  • bysource: members are sorted in the same order as they appear in code. This is the default option.

:module-member-order: alphabetical | groupwise | bysource

Overrides lua:autoobject:member-order for modules.

:title: <text>

For modules, controls whether a title is inserted between module description and documentation of its members.

:index-table:

Adds lua:autoindex to the toplevel module.

:index-title: <text>

Allows overriding title of the lua:autoindex section.

:inherited-members-table:

Adds lua:other-inherited-members to all classes.

:annotate-require: always | never | auto | force

Adds information about how to require a module.

Options are:

  • always: always show how to require a module;

  • never: never show how to require a module;

  • auto: only show how to require a module if the module’s exported type is not a table;

  • force: always show how to require a module, even if lua analyzer didn’t export this information.

Warning

LuaLs only supports never and force.

:require-function-name: <name>

Allows overriding name of the require function for lua:autoobject:annotate-require.

:require-separator: <str>

Allows overriding separator for lua:autoobject:annotate-require.

.. lua:auto*::

In addition to lua:autoobject, there are lua:autodata, lua:autoattribute, lua:autoclass, and other lua:auto* directives.

They work like lua:autoobject, but apply their doctype to the documented object (if !doctype was set in source code, it shouldn’t conflict with the used directive).

They also allow overriding object’s signature, which may be useful when automatically generated signature is too long:

.. lua:autofunction:: logging.getLogger(name: string?): logging.Logger

```{lua:autofunction} logging.getLogger(name: string? = ...): logging.Logger
```
Example output
logging.getLogger(name: string? = ...): logging.Logger

Get logger with the given name, or create one if it doesn’t exist.

Parameters:

name? (string) – logger name. Uses current module name if empty.

Returns:

logger (logging.Logger) – logger with the given name.

.. lua:autoindex:: module-name

Creates a table that references all documented objects in the module module-name. This is useful for creating module’s table of contents.

If module-name is not given, lua:autoindex will use current module.

If given, module name must be absolute, even if this directive appears after lua:module.

.. lua:other-inherited-members:: class-name

Creates a list of all members that class class-name inherited from its bases but didn’t document with lua:autoobject:inherited-members.

If class-name is not given, lua:other-inherited-members will use current class.

If given, class name must be absolute, even if this directive appears after lua:module.

Controlling generation from code comments

When using lua:autoobject in recursive mode, it is sometimes necessary to override its options for some objects. To do this, you can include specially formatted comments to your documentation.

To override any lua:autoobject setting for a particular object, use @doc comments. For example, here we enable lua:autoobject:special-members and exclude __tostring for class Foo:

--- Some class documentation...
---
--- @doc special-members
--- @doc exclude-members __tostring
--- @class Foo

You can also specify which type of object is being documented by using a @doctype comment. For example, here we use @doctype const to indicate that a certain variable should be documented as lua:const:

--- Some const documentation...
---
--- @doctype const
--- @type string
foo = "bar!"

Note

LuaLs-style !doc and !doctype comments are also supported. However, we recommend switching to @doc and @doctype because EmmyLua provides a proper syntax highlighting for them.

To override any lua:autoobject setting for a particular object, use !doc comments. For example, here we enable lua:autoobject:special-members and exclude __tostring for class Foo:

--- Some class documentation...
---
--- !doc special-members
--- !doc exclude-members: __tostring
--- @class Foo

You can also specify which type of object is being documented by using a !doctype comment. For example, here we use !doctype const to indicate that a certain variable should be documented as lua:const:

--- Some const documentation...
---
--- !doctype const
--- @type string
foo = "bar!"