Define Markdown schema for API reference docs

[mark-wiemer]

Right now, the docs are all in lua_api.md#core-namespace-reference, where the only requirement is "valid Markdown" (really, it just needs to pass human review). This has resulted in various issues, namely that some function args have unclear types. A stricter Markdown schema would ensure that all necessary information is documented for each function, and a check can be automated. This issue focuses simply on defining the schema, not yet implementing the checks.

Criteria

• Return types documented
• Argument types documented
• All information about the function should be nested within the same section (see below)
• more to be discussed...

---

All information about the function should be nested within the same section

Details

For example, in the snippet below, the table description is not syntactically nested under the list, and would be hard to parse:

- `core.get_game_info()`: returns a table...
{
   id = string,
   ...
}
- `core.get_world_path()`: ...

When rendered, the table description ends the list, then the next bullet starts a new list:

• core.get_game_info(): returns a table...

{
   id = string,
   ...
}

• core.get_world_path(): ...

---

A more correct snippet would indent the table definition:

- `core.get_game_info()`: returns a table...
   {
      id = string,
      ...
   }
- `core.get_world_path()`: ...

Now the table description is clearly nested under the get_game_info list item:

• core.get_game_info(): returns a table...

  {
     id = string,
     ...
  }

• core.get_world_path(): ...

Secondary considerations

• Ease of scanning plaintext

[mark-wiemer]

Ref https://github.com/mark-wiemer/hello-hello/blob/485714fbd0245d433617117654ef27bf407a42e4/packages/remark/lua_api_transformed.md

[SmallJoker]

I know this misses the point, but as for API reference I prefer a compact notation such that it's easy to scroll through in plaintext format.
EDIT: This also includes preserving the indent level to better see the scope of the code block (or listing point).

[appgurueu]

I think viewing this as a "Markdown schema" issue is putting the horse before the carriage.

We need some suitable, terse notation for types and documentation from which (interlinked) Markdown docs can then be generated along with typedefs (for whichever tool, be it a "Lua language server", a typed Lua dialect, or something like TypeScript).

Ideally, this would even let us generate the bindings (see also luanti-org/luanti#16685).

[mark-wiemer]

@appgurueu if you're suggesting parsing the Lua or C++ code comments directly, I'm not sure that will be very useful. We'll have to ensure every file already documented in lua_api.md has the same level of documentation in the code itself. There has been resistance there about adding verbose method header comments. I can see both sides of the argument as reasonable. I opted to move forward with what we had now. Much less rewriting this way. As always, happy to discuss.

[appgurueu]

if you're suggesting parsing the Lua or C++ code comments directly

That would be one option, but it's not really what I'm suggesting.

The point I wanted to make is that we should start with a suitable machine-readable format, not try to turn what is intended to be a human-readable format into a machine-readable format.

I have previously referenced how LÖVR does it, which is using a custom Lua format, but really any kind of general purpose "object notation" can be used, be it JSON, YAML, TOML, or whatnot, down to S-expressions. However, some may be less suitable than others; e.g. JSON will end up rather verbose and has no comments, YAML is a mess.
I would prefer Lua because I know that it can be made sufficiently concise, does not require anyone to learn a new notation (it's safe to assume that someone working with Luanti needs to learn Lua), and is extremely customizable.

Ultimately we will have to try it and see. I'll see if I can get a PoC for a Lua-DSL-based approach up in a couple days.

[mark-wiemer]

Let's move this discussion into the high-level parent issue