machine and human readable documentation

[Bilal2453]

The initial work needed for adding documentation.

This PR only adds documentation for lminiz, and adding the rest can be done later, mainly so I can get feedback before I continue working on the rest.

You may also review what the introduced docs directory looks like here.

The documentation for lminiz should be fully done, feedback with the following would be appreciated:

• the Markdown output. Right now it generally follows that of the luv docs markdown.
  • Currently I have two formats for returns, luv-docs style and an expanded one, which one do you prefer more?
• the machine readable Lua format.

The goal here is that once I finish some of the luvi stuff I move this work to include luv as well, see luvit/luv#632.
Potentially might also provide a LuaCATS generator that will be used for luvit-meta.

[truemedian]

From a maintenance perspective it would be much more beneficial to use something like ldoc to document the interface in C where it is defined or somehow adapting LuaCATS into something that would work in a C comment.

I understand LuaCATS itself doesn't support reading information from C modules so perhaps the tooling could generate the necessary LuaCATS meta file, but completely separating the documentation from the implementation is just asking for them to become out of sync.

[Bilal2453]

Good point frankly. Although that is going to be very hard to achieve practically. I believe this shouldn't explicitly be about LuaCATS annotations, rather just a machine readable format.

some challenges:

• implement a way to convert ldoc/luacats into a machine readable format from C and Lua code (in this case for luvibundle/luvipath etc).
• implement a way to add/remove new type of information into the annotations without much trouble.
  • should include the concept of classes/sections/aliases/etc.
• also document luv in-code, which is pretty much not possible as of now I would say?
• have separate files for documentation pages not part of any code (main page/explanation pages).

So I am not sure honestly as it would be more flexible to do it this way, perhaps it would still be possible to migrate the work into code later on? be it an annoying thing to deal with.

I am honestly debating whether I should just completely overkill this and write a fully fledged parser, to be able to just generate and parse any doc format from anywhere.