Write documentation for the Lua API and generate markdown for the docs

[lionkor]

Related to #355. Basically, we want to generate the Lua Docs page from the LuaAPI.cpp or LuaAPI.h file. This can be a script, it can use doxygen, it can use whatever.

It needs to:

• Generate markdown for the docs.beammp.com page (in the right flavor)
• Make the script maintainable and run it in CI/CD

[carsakiller]

As mentioned before, I would be interested in helping writing definition files for the API for use with the Lua Language Server. The definition files could be generated at the same time as the markdown to make things easier to maintain and more consistent.

We could potentially write all the documentation using LuaCATS annotations and then use the export documentation feature of the language server to generate JSON and Markdown from the definition files. Although this would require some testing.

The other option is to define the entire API in JSON/XML/YAML and then generate the Markdown and LuaCATS annotations from that. It would allow more customization and control, but would also require a custom script.

[lionkor]

@carsakiller would you be interested in doing this? :) You seem pretty knowledgable on that.

[carsakiller]

@lionkor, sure! I'm thinking of making a CLI tool that can:

• Read in LuaAPI.cpp and generate a basic description of the functions (name, param types, return types). This will help with the first generation and with large changes to the code, as we can at least get basic docs for everything that exists in-code.
• Combine the above generated info with custom “supplementary” data. This can include descriptions, examples, etc. for richer documentation.
• Output to Markdown for the docs site and output to LuaCATS annotations for Lua Language Server.

An alternative to the “supplemental” file is we embed the descriptions, examples, etc. as comments (to be parsed still) in the C++ code. This means it will all be in one place at least, but it will make the C++ file larger and cluttered. Curious about your opinion on this.

[carsakiller]

I wrote some quick code to parse LuaAPI.cpp and to read in some YAML to fill in descriptions and examples:

doc.yaml

functions:
  LuaAPI::MP::GetOSName:
    description: >
      Get the operating system that the server is currently running on. Possible values are `Windows`, `Linux`, `Other`.
    examples:
      - |
        local os = MP.GetOSName()
        print("Currently running on " .. os)
  LuaAPI::MP::GetServerVersion:
    description: >
      Get the current semantic version of the BeamMP Server.
    examples:
      - |
        local version = MP.GetServerVersion()

        local major = version[1]
        local minor = version[2]
        local patch = version[3]

Merging of the two is then output as some Markdown:

Markdown Output

# MP.GetOSName
Get the operating system that the server is currently running on. Possible values are `Windows`, `Linux`, `Other`.

`MP.GetOSName() -> string`

## Examples

```lua
local os = MP.GetOSName()
print("Currently running on " .. os)
```

# MP.GetServerVersion
Get the current semantic version of the BeamMP Server.

`MP.GetServerVersion() -> { number, number, number }`

## Examples

```lua
local version = MP.GetServerVersion()

local major = version[1]
local minor = version[2]
local patch = version[3]
```

We can already start to see some issues here where, sure, the types of string and { number, number, number } are not wrong, but they aren't very helpful. Saying "Windows" | "Linux" | "Other" would be much more helpful. However, there is a lot of info that cannot be inferred from the C++ function signatures:

Assertions

For MP.Set(ConfigID: number, NewValue: any) -> void, NewValue is asserted as either a bool, int, or string in the function body, but it is not made obvious from the param type of sol::object and would be very difficult to discover by reading the function body. Ideally we would be able to say NewValue: number | string | boolean.

Mappings

In LuaAPI.cpp, the util functions like JsonEncode, etc. are found under the MP namespace, when they are actually mapped into a Util table in TLuaEngine.cpp. This would also be very difficult to discover through analysis of the code.

---

To fix the mapping issue, we could create a Util namespace, like the MP and FS namespaces in LuaAPI.cpp, and then it can be parsed out just fine.

For the other problems, we need a better way to define types, as they will appear for Lua plugins. We could keep expanding the doc.yaml to allow defining of param types and unions and whatnot… but at that point, we are basically defining it all in the YAML and there is no real point in parsing the C++. I think it would be better to instead document it alongside the actual source code in LuaAPI.cpp. Perhaps via comments (roughly) like:

// Description of function here!
// @param ConfigID number Description of this parameter
// @param NewValue number|boolean|string  Description of this parameter
// @return boolean success Description of this return value
// @example Example Name
// ```
// ...
// ```
// @example Example2
// ```
// ...
// ```
void LuaAPI::MP::Set(int ConfigID, sol::object NewValue) {

Thoughts, @lionkor?