lua-doc-extractor


Extracts lua documentation from C-style comments.

Install

``sh
$ npm install -g lua-doc-extractor
`

Usage

$3

#### Input

`cpp
/*
* Main API
* @table Api
* @field Version integer
*/

/*
* The absolute path to the executable.
* @global ExecutablePath string
*/

/*
* @enum NameType
* @field FirstName 1 First name.
* @field LastName 2 Last name.
*/

/*
* @field NameType.FullName 3 Full name, including middle names.
*/

/*
* Get name by ID
* @function Api.GetName
* @param id integer The integer of the person.
* @param nameType NameType Which name to return.
* @return string name The full or first name of the person.
*/
int SomeClass::GetName(lua_State *L)
{
`

#### Output

`lua
---@meta

---Main API
Api = {
---@type integer
Version = nil
}

---The absolute path to the executable.
---@type string
ExectablePath = nil

---@enum NameType
NameType = {
--- First name.
FirstName = 1,

---Last name.
LastName = 2,

---Full name, including middle names.
FullName = 3
}

---Get name by ID
---
---@param id integer The integer of the person.
---@param nameType NameType Which name to return.
---@return string name The full or first name of the person.
function Api.GetName(id, nameType) end
`

$3

Process files:

`sh
$ lua-doc-extractor some-file.cpp other-files/*.cpp --dest output
`

Show usage:

`sh
$ lua-doc-extractor --help
`

To add GitHub source links to the exported library. Provide the --repo argument.

`sh
$ lua-doc-extractor */.cpp --dest library --repo https://github.com/beyond-all-reason/spring/blob/62ee0b4/
`

$3

Lua docs in document comment blocks (/* */) will be parsed.

$3

All lua language server annotations can be used, some with special handling. Some additional annotations are required by lua-doc-extractor.

#### @global

`
@global [description]
`

Defines a global variable.

#### @field

`
@field [description]
`

Add fields to a table (@table, @class or @enum) by including them in the same comment.

`
@field

. [description]
`

You can also add fields to a table defined in a different comment.

#### @function

`
@function [description]
`

Defines a global function.

`
@function

. [description]
@function : [description]
`

Adds a function to a @table or @class defined in a different comment.

Should be paired with @param, @return and @generic attributes.

#### @table

`
@table
`

Defines a global table. Fields can be added with @field.

#### @enum

`
@enum
`

Defines a global table marked with the @enum attribute. Entries can be added with @field.

#### @class

`
@class
`

Defines a class. Fields can be added with @field, methods can be added with @function`.

Contributing

PRs accepted.

License

MIT