Time Nick Message 03:41 MTDiscord Neat 🙂 going to explore LuaCATS + LuaLS addon for a while, it's looking pretty promising. There are limitations I'm sure and we may very well realize the whole LuaLS code is a huge mess, but if it works decently well it'll be much easier than defining our own alternative to LuaCATS and building our own parser for it 🙂 LuaLS supports exporting to Markdown anyway 😉 https://luals.github.io/wiki/export-docs/ Images will be 03:41 MTDiscord posted in the GH issue shortly: https://github.com/luanti-org/docs.luanti.org/issues/296 03:41 MTDiscord https://cdn.discordapp.com/attachments/926231483155378176/1446708019680383026/image.png?ex=6934f756&is=6933a5d6&hm=3a17fe8b373b575bfc232877b96be0ee3b841793586f1f72c6993a9389c64c47& 03:41 MTDiscord https://cdn.discordapp.com/attachments/926231483155378176/1446708020028375076/image.png?ex=6934f756&is=6933a5d6&hm=271e634e29f99fcd9f6dd3c4bc1c738626cc2766d70c9baad67611a31e36391c& 03:41 MTDiscord https://cdn.discordapp.com/attachments/926231483155378176/1446708020330369156/image.png?ex=6934f756&is=6933a5d6&hm=31caee5d3beb7b09c83631b5104c3b107754ca0af579bd5a09b6c671e32d0234& 04:42 MTDiscord If anybody wants to try the LuaCATS-to-Markdown converter in LuaLS, be my guest--it's sure not working for me! ## Limitations of LuaCATS + LuaLS - Can only officially mark functions as deprecated, nothing else, but a workaround exists - @deprecated is ignored on globals when assigned by another global - Includes workaround used in sample.lua - Feature Request: Deprecate fields and parameters - Export document - might 04:42 MTDiscord throw errors out of the box, but a workaround exists - Error when exporting Lua language server documentation - always goes to the log path by default - Feature: add setting to configure default path for exporting documentation (VS Code) - includes tons of extra types after applying the workaround - unclear if the workaround had anything to do with this - goal is to export just the luanti_api.lua into doc.md, unclear where 04:42 MTDiscord other types are coming from https://github.com/mark-wiemer/hello-hello/blob/main/packages/luanti/doc-schema/luacats-findings.md 04:45 MTDiscord @a.corp.serot I have not forgotten about your gist 🙂 my next steps are to toy around more with LuaCATS and see if I can get a meaningful snippet of docs translated from Markdown into LuaCATS for each section. Then I'll dive deep into your gist and see what we can do to really enforce types. That said, I think we will be starting a bit smaller with this v1 and just working on getting something to a more consistent, 04:45 MTDiscord machine-readable format. From there it should be much easier to "add features" and narrow down types as you're requesting. This'll be a long process 🙂 04:52 MTDiscord i suggest you don't use LuaCATS, as you'll be bounded to what information that LuaCATS can provide 04:53 MTDiscord i've hit the wall using it to annotate luanti's API 04:53 MTDiscord same goes for EmmyLua 04:59 MTDiscord if you read through some of LuaLS's issues, you'll come to realize that it's incomplete in the sense that there are features missing where you expect. i don't have confidence that the documentation generator fully captures everything 05:02 MTDiscord as for the work of translating the markdown to luacats and emmylua, you can defer that work to people who wants to use the language servers (like me) 05:05 MTDiscord i don't want to force you to learn the quirks of both language servers, of which there are plenty 05:51 MTDiscord If we don't use an existing Lua documentation format, we'll have to make our own, which is a whole boat of issues :/ 06:15 MTDiscord bahahaha you're corpserot lol 06:45 MTDiscord yeah lol, look at my @ 06:53 MTDiscord The whole point was to just define a markdown schema that is consistent enough that any format could be generated from it 06:53 MTDiscord Not our job to make the language server definitions 06:54 MTDiscord (Well, its my job, but only because of the extension, nothing to do with docs) 13:34 MTDiscord such a schema is surprisingly difficult, but I'll continue exploring that approach to see if I'm missing something 13:56 MTDiscord The highest level goal is getting this info into an IDE so modders have quick access to it while writing. The medium goal is making the docs programmatically parsable so they can easily be put into an IDE and maintained. The lowest goal was defining a markdown schema to make the docs programmatically parsable. There are other ways to make the docs programmatically parsable, like using LuaCATS. Any approach will have its drawbacks, I 13:56 MTDiscord don't know enough yet to argue for one approach very strongly. So the experimentation continues 🙂 14:24 MTDiscord @a.corp.serot you say not to use LuaCATS or EmmyLua, do you have any suggestions on what we should explore instead? 14:26 MTDiscord i think the markdown idea was alright, because unless you have an appetite to tinker with code in emmylua or luals you'll run into a wall of what information you can encode. 14:28 MTDiscord @mark.wiemer also, one idea i haven't pursued yet is to soft fork lua annotation, making a superset. basically, get luals or emmylua to parse it into JSON or smth, and then go through another layer of parsing extra information encoded within the symbol/type description 14:29 MTDiscord it's kinda janky, hence i don't know if its worth pursuing that 14:34 MTDiscord to clarify, from my perspective, i believe the goal isn't really about getting the information into an IDE. it's just a consequence of the bigger goal 14:34 MTDiscord that is, the goal to make a detailed parseable specification of Luanti's Lua API. there's no paths for the existing language servers to e.g. know anything about Luanti's startup-main-async-async_mapgen even if you were to make a specification 14:35 MTDiscord another example is that luacats have no idea what a player name constraints are, and we can't even express that 14:48 MTDiscord I haven't explored Teal, but if we really want strong types like that, does it sound useful? Otherwise it even sounds like you're describing a TypeScript-level complexity, which would be get another language. The problem with a Markdown schema is we'd have to write the definition and parser ourselves, it'd be great to use something like LuaCATS or Teal or TypeScript where the doc format has already been built out and tested in 14:48 MTDiscord ecosystems. I accept that LuaCATS has bugs but it's better than starting from complete scratch, I think. If it's not good enough, that's fine, we just need to find something that is. Much easier to find something than to create it from scratch 15:44 MTDiscord if you're gonna use existing annotation langs, you'll have to contend that you can't express some form of information as cleanly. one thing i've struggled with lua annotation is that you can't narrow numbers and integers any further. 15:46 MTDiscord perhaps typescript may be better 15:46 MTDiscord Have you seen TSDoc? It's Turing complete and has tons of support for extremely complex types 15:47 MTDiscord I consider TSDoc an existing annotation lang, problem is that it'd be yet another language in the project 15:47 MTDiscord but i kinda don't have confidence in proposing typescript of all things to be the way to express the API spec 15:47 MTDiscord Why not? 15:47 MTDiscord well, aside from introducing another language, it's also one that has very little to do with luanti aside from providing the spec info 15:48 MTDiscord ideally, we would use something that's familiar to project members 15:50 MTDiscord Yeah, I agree. But it seems the Lua ecosystem just doesn't have the expressive power we need, right? If we go with an existing approach in the Lua ecosystem, like LuaLS, we'd eventually hit an expressive wall like you did and have to start anew? I do want to start something that can evolve into a very long-term solution, but maybe I'm getting ahead of myself. That said, your LuaCATS project is pretty comprehensive it looks like, 15:50 MTDiscord just not super deep on specific types. Is that a fair assessment? 15:52 MTDiscord it has a lot of problems that i haven't documented but the express intent was to write an annotation to my best extent possible, along with overhauled descriptions since i need to read the implementation anyways 15:52 MTDiscord the types being unspecific is just one of them 15:55 MTDiscord I think we need a fixed place to compare and contrast every approach. Just to clearly state things like "JSON, bad support for multi-line descriptions. YAML, too weird. LuaCATS, limited type expression and stalled development of underlying parser. TypeScript, unrelated to project but very expressive and supported by tooling. Markdown, possible but would require custom schema and writing custom parser" etc etc as we explore options 15:55 MTDiscord like Teal too 15:56 MTDiscord Do you know of any Teal-based tools? Is it worth exploring? 15:56 MTDiscord i advise against teal, since it's in a similar fate to luarocks 15:57 MTDiscord the creator not really having time or energy to fully resolve their respective kinks 16:00 MTDiscord the thing is, even with typescript, i think you'll need to decide a way to impart information that typescript alone cannot express. namely whether any given function is available in X thread/environment 16:00 MTDiscord Hmm, good to know. Is stuff like that included in your gist? 16:01 MTDiscord i don't think so. that was planned to be included in the overhaul before i give up on it :( 16:01 MTDiscord It's a big project!! 16:02 MTDiscord mostly because the realization that i'm hitting the wall in so many different ways all at once lol 16:02 MTDiscord man, it was so naive thinking that i can just express luanti API perfectly with luacats or even emmylua 16:03 MTDiscord i can't even easily express what fields are gueranteed to be populated by the engine 16:04 MTDiscord I think we should focus on what's documented in lua_api.md. if there are issues there already about correctness, missing info, etc, let's start some PRs just to clean it up while we think about things. Even if it's not programmatically parsable today, at least it'll be written in the source of truth, that way we don't forget it later 16:05 MTDiscord that's the approach andro took in their annotations (the minetest.land one) 16:07 MTDiscord as in, it uses lua_api.md as the source of truth (with some corrections i had to help because the docs are ambiguous in certain places) 16:08 MTDiscord so, if you want a place to start, the annotations there aligns more closely with your desired approach 16:35 MTDiscord Have you opened PRs in the luanti repo to correct issues in lua_api.md? 16:58 MTDiscord no, i think the parts to correct need a larger overhaul than me simply correcting small bits of it 17:00 MTDiscord for instance, default values really should be documented in some way but that constitutes a pretty big change 17:02 MTDiscord as for ambiguity from wording, it's kinda subjective. i don't really wanna get out there and proclaim "my wording best describes the thing!" 17:03 MTDiscord english isn't even my first language, and i'm not particularly excellent in it 17:10 MTDiscord A PR is just an idea, not a proclamation of superiority 🙂 I think PRs are the best way to show which areas you think can best be improved. I'll read your gist in the meantime. Busy today but should have a few hours, esp tomorrow 17:21 MTDiscord well, it has to improve the original text in some way and that's quite subjective esp when there's no new information added or corrected. i don't really like to participate in that kind of discussions 17:25 MTDiscord Fair enough 17:59 MTDiscord Edited https://github.com/luanti-org/docs.luanti.org/issues/296 to include this section at the bottom: Considered approaches (none fully ruled out, basic thoughts noted): - EmmyLua: still Lua, decent underlying parser, development recently picked up. Not expressive enough. - JSON: tons of tooling support. No clear schema, hard to handwrite. - LuaCATS: still Lua, has decent underlying parser. Not expressive enough, underlying parser 17:59 MTDiscord development stalling - Markdown: very expressive, tons of tooling support. No clear schema yet defined, no parser built. - Teal: still Lua, more type support. Underlying development stalling - TOML: not explored - TypeScript: extremely complex types supported, tons of tooling support. Not Lua, not used elsewhere in Luanti repo - YAML: tons of tooling support. No clear schema, can be easy to make mistakes Feel free to add more thoughts, there is 17:59 MTDiscord much exploration to be done. Haven't read the gist quite yet, will probably do that on the bus now 🙂 18:12 MTDiscord they can be grouped into 2 categories. (1) JSON, TOML, YAML, Lua DSL/LOVE-style, Markdown (2) EmmyLua, LuaCATS, Teal, Typescript 18:13 MTDiscord i think it's safe to say that if the other devs think the spec doesn't need any complex types any of the (1) category can be used 18:37 MTDiscord I'm curious how and why you separate them into two categories 18:38 MTDiscord And I read the gist, very helpful info. Will definitely keep in mind that we need to include context/env, and the actions (read, modify, define) that are valid within each context/env 18:41 MTDiscord category (2) has a type system built-in :) 18:51 MTDiscord As in, remark.js is not going as you had hoped? 18:53 MTDiscord I agree; The goal should be primarily to make the source of truth more versatile. Getting the API into IDEs is definitely a driver, though 22:35 MTDiscord Haven't done any implementation work since last week. The devil is in the details when it comes to schemas. Best to use ones that already exist, if possible, so I explored LuaCATS. That said, I do have some ideas to get started with. But our own custom schema and parser will always be a lot of reinventing the wheel compared to something that already exists