Description

Luals2dox is an input filter for Doxygen that filters Lua files.

Lua files shall be annotated for use with LuaLS, the Lua Language Server, that is a necessary requirement for Luals2dox.

Usage

Required files

• Doxyfile, Doxygen configuration file.
• doc.json, documentation file created by LuaLS.

Put these files into your project documentation directory where you want to compile the documentation.

File Doxyfile

Create a standard Doxyfile with

$ doxygen -g

and edit this file as described in Section Configuration in Doxygen.

File doc.json

Run the following command in your project documentation directory to create file doc.json.

$ lua-language-server --doc path/to/src/code/ --doc_out_path ./

Run doxygen

Run doxygen to generate the documentation.

$ doxygen

Updating the documentation

All you have to do to update the documentation is to rerun Doxygen. You do not need to update doc.json manually, as this is done by luals2dox automatically.

Configuration in Doxygen

For using luals2dox in Doxygen apply the following configuration settings, either manually or by using doxywizard.

Mandatory Settings

FILE_PATTERNS

Add .lua file name extension to FILE_PATTERNS. (See Section Expert/Input in doxywizard.)

FILE_PATTERNS = *.lua

FILTER_PATTERNS

Add luals2dox as a filter for .lua files. (See Section Expert/Project in doxywizard.)

FILTER_PATTERNS = *.lua=luals2dox

EXTENSION_MAPPINGS

Since luals2dox creates pseudo C++ code, you have to tell doxygen to use its C++ parser to understand .lua files. (See Section Expert/Project in doxywizard.)

EXTENSION_MAPPING = .lua=C++

LaTeX Output

Unicode characters

Luals2dox uses Unicode characters that are not defined in LaTeX by default. Therefore it’s necessary to define these characters in a user defined LaTeX style file, e.g. mystyle.sty. (See Section Expert/LaTeX in doxywizard.)

LATEX_EXTRA_STYLESHEET = mystyle.sty

File mystyle.sty shall contain the following definitions:

\DeclareUnicodeCharacter{2772}{[}
\DeclareUnicodeCharacter{2773}{]}

Optional Settings

ALIASES

A summary page of asynchronous functions, functions marked with @async (see LuaLS annotations), can be created with the following alias. (See Section Export/Project in doxywizard.)

ALIASES = "async=@xrefitem note \"Asyncronous Function\" \"Asyncronous Functions List\"

Debugging

Pseudo C++ Code

You can call luals2dox from the command line to check the pseudo C++ code that it creates.

$ luals2dox path/to/file.lua

Pitfalls to avoid

@-Commands

It’s common to write LuaLS annotations without any whitespace characters between --- and @. E.g. ---@param foo string. While this works fine with LuaLS specific @-commands, it doesn’t work with doxygen specific @-commands.

The following does not work:

---@code{.lua}
--- foo = { a = 1 }
---@endcode

In order to use doxygen specific @-commands you have to put a whitespace character between --- and @.

--- @code{.lua}
--- foo = { a = 1 }
--- @endcode

To be more specific: This is an issue if the comment block is passed through LuaLS’ doc.json file. However, some comment blocks, like @file, are read directly from the lua file (not via doc.json), where this is not an issue. Anyway it’s always save to add a whitespace character for doxygen specific @-commands.