gludoc
Gludoc is a VSCode extension for generating Lua documentation from Lua source
code.
You should be documenting files that are intended to be documentation lua
files instead of your actual code files. This is because Gludoc will generate
documentation for all Lua files it can find in your workspace that begin
with ---@meta <documentname>; this must be the very first line of the file
and the file must be a Lua file.
See the example.
Such documentation is also useful with the Lua Language Server extension.
It is worth mentioning that Gludoc is not a replacement for LDoc or LuaDoc
It is simply a tool to help you generate documentation for your Lua code. It
is not intended to be a fully featured documentation tool, rather, it is
intended to be a quick and easy way to generate documentation for the lazy
coding git who just wants to burp out some docs, potentially, for inclusion
in a wiki or documentation site. If you want a fully featured documentation
tool, you should use LDoc or LuaDoc. I just find them too ~~complicated~~
heavyweight for my general needs.
Protips
- Keep your documentation files in a separate directory from your code files.
- Hmm. Idk anymore yet. Maybe later. 🤷🏻
Features
Gludoc will trawl through your workspace and generate documentation for all
Lua files it can find.
It parses Lua Language Server documentation comments and uses these to generate
markdown documentation.
Gludoc supports the following tags:
Param
--- @param <type> <name> - <description>
Return
--- @return <type> # <description>
Example
--- @example
--- ```lua
--- <example>
--- <more example
--- <even more example
--- ```
Description
Anything that doesn't match a supported tag is treated as a description.
Example
Given the following Lua code:
---@meta DateClass
------------------------------------------------------------------------------
-- DateClass
------------------------------------------------------------------------------
if false then -- ensure that functions do not get defined
---@class DateClass
---Converts a number of seconds into a human-readable string. By default, the
---result is returned as a table of three strings. However, if the `as_string`
---parameter is provided, the result is returned as a single string.
---
---@name shms
---@param seconds number - The number of seconds to convert.
---@param as_string boolean? - Whether to return the result as a string.
---@return string[]|string # The resulting string or table of strings.
function date.shms(seconds, as_string) end
end
The following markdown documentation would be generated:
# DateClass
## date.shms
Converts a number of seconds into a human-readable string. By default, the
result is returned as a table of three strings. However, if the `as_string`
parameter is provided, the result is returned as a single string.
**Parameters**
- `seconds` (`number`) - The number of seconds to convert.
- `as_string` (`boolean?`) - Whether to return the result as a string.
**Returns**
`string[]|string` - The resulting string or table of strings.
Contributes
This extension contributes the following to the VSCode command palette:
[Gludoc] Generate Lua Documentation from current workspace: Generates
documentation for the current workspace.
Release Notes
0.1.0
Initial release of Gludoc.
0.2.0
Major update to Gludoc. Now supports @name for functionsd and @meta for
describing the module name at the top of a file.
1.0.0
Adding license and also previously added support for multiple return values.
Fromat icons created by PixelX - Flaticon[^1]
[^1]: This is not a typo by me, this is the attribution required by Flaticon for the format icons used in the extension.
