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.
@see
markers can sometimes be broken. We recommend using theseealso
directive instead.@deprecated
markers do not add any note to the documentation. We recommend providing an explicit message with thedeprecated
directive.@nodiscard
and@operator
markers are not exported.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.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 directive¶
- .. 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:¶
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:¶
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:¶
- :protected-members:¶
- :package-members:¶
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:¶
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:¶
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:¶
A comma-separated list of members that should not be documented.
- :globals:¶
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:¶
Specifies how to generate documentation for classes if
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:¶
Specifies how to generate signatures for classes if
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.
If
lua:autoobject:members
,lua:autoobject:globals
,lua:autoobject:undoc-members
,lua:autoobject:private-members
,lua:autoobject:special-members
, orlua:autoobject:inherited-members
are given as flags, they are propagated to all documented objects.If they’re given as list, they are not propagated.
Options from
lua_ls_default_options
are applied to all recursively documented objects.
- :member-order:¶
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:¶
Overrides
lua:autoobject:member-order
for modules.
- :title:¶
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:¶
Allows overriding title of the
lua:autoindex
section.
- :inherited-members-table:¶
Adds
lua:other-inherited-members
to all classes.
- :annotate-require:¶
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
andforce
.
- :require-function-name:¶
Allows overriding name of the
require
function forlua:autoobject:annotate-require
.
- :require-separator:¶
Allows overriding separator for
lua:autoobject:annotate-require
.
- .. 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 withlua: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!"