Automatic generation of documentation

[sondr3]

First off, thanks for mlua, it's a great crate and I've used it for a few projects now without much fuzz. I've also been playing around with its Haskell counterpart, hslua which has a great feature which I was wondering you felt could be valuable to mlua: documented functions:

factorial :: DocumentedFunction e
factorial = defun "factorial"
  ### liftPure (\n -> product [1..n] :: Prelude.Integer)
  --                 get arg      type of arg      name  description
  <#> parameter      peekIntegral "integer"        "n"   "input number"
  =#> functionResult pushIntegral "integer|string"       "factorial of n"
  #? "Computes the factorial of an integer."
  `since` makeVersion [0, 1, 0]

We can ignore the sigils and stuff like that, but this creates a Haskell->Lua function that is documented in the source code, enabling this like generating documentation for Markdown or types for use in the LSP and so on.

Example markdown documentation

factorial (n)

Computes the factorial of an integer.

Since: 0.1.0

Parameters:

n : input number (integer)

Returns:

• factorial of n (integer)

I think this would be a really nice addition, or maybe separate crate, for the mlua ecosystem because I keep forgetting to update either or both the documentation and types all the time, and having them automatically being kept in sync would be great. I have seen that the tealr crate has something like this for Teal, so there is some prior art from @lenscas.

[lenscas]

I have seen that the tealr crate has something like this for Teal, so there is some prior art from @lenscas.

tealr is basically just a wrapper around mlua. Yes, the original focus was on getting Rust <-> Teal better but with Teal compiling to Lua (or even just running directly on the lua VM and getting compiled on the fly) there is no reason it wouldn't help you out if you are just looking for FFI with lua rather than teal.

In fact, nowadays I would even say that Rust <-> Teal isn't even the main focus of tealr anymore. Yes, I do keep teal's typesystem in mind both in how types get shown in documentation as well as what it can and can not model, however most features inside tealr now either resolve around documentation or making it easier to create types that get shared with lua.

With this all out of the way: I wouldn't mind it if mlua starts taking features from tealr. I am also more than happy to support alternative formats for tealr_doc_gen if it means that mlua can do a lot of the things that tealr does on its own. I do however would appreciate some help with this if the changes are drastic.