Time Nick Message 00:04 MTDiscord <luatic> The entire empty capture group is weird IMO. Seems C++y to me that people prefer indices over copying strings (arguably it does offer better performance in some cases though). 00:05 MTDiscord <luatic> Note: > As a special case, the empty capture () captures the current string position (a number). For instance, if we apply the pattern "()aa()" on the string "flaaap", there will be two captures: 3 and 5. From the reference manual. 00:16 MTDiscord <Benrob0329> ahh, thanks 00:19 MTDiscord <Benrob0329> pushed to the vector PR 00:21 MTDiscord <luatic> mergeable, should be squashed 00:25 MTDiscord <luatic> merged 00:27 MTDiscord <Benrob0329> thanks, although squashing hasn't been our policy so far 00:27 MTDiscord <Benrob0329> RE "Then the macro is inaccurate. Should say "deprecated-following"." - "the foo following" is valid 00:28 MTDiscord <Benrob0329> I mean, what's valid is relative I suppose, but afaik it's a normal construct 00:28 MTDiscord <luatic> Squashing is a good idea if the individual commits don't add much value. 00:29 MTDiscord <luatic> The course of a PR often is rather messy. The commits don't need to reflect that IMO. 00:30 MTDiscord <Benrob0329> inb4 Warr again 00:30 MTDiscord <Benrob0329> We need a merge, squash, and rebase policy probably 00:31 MTDiscord <luatic> Alright. Now as soon as we get https://github.com/minetest/minetest_docs/pull/12 merged, we can start the standardization. 00:31 MTDiscord <luatic> Standardization ;) 00:31 MTDiscord <Benrob0329> Well yes but actually yes 00:31 MTDiscord <luatic> https://github.com/minetest/minetest_docs/issues/19 01:15 MTDiscord <GreenXenith> style/howto standardization draft PR open https://github.com/minetest/minetest_docs/pull/20 01:18 MTDiscord <Jonathon> looks reasonable so far 02:06 MTDiscord <Benrob0329> @GreenXenith <<Vehicle Properties>> should be the section link, iirc it excludes formatting marks 02:06 MTDiscord <Benrob0329> If it doesn't work, try with the backticks 02:38 MTDiscord <Benrob0329> @GreenXenith reviewed your PR 03:06 MTDiscord <GreenXenith> hows this? 03:06 MTDiscord <GreenXenith> https://cdn.discordapp.com/attachments/926231483155378176/928122208172249138/unknown.png 03:06 MTDiscord <Jonathon> looks rather confusing 03:07 MTDiscord <Jonathon> (even though i know what your are trying to convey) 03:07 MTDiscord <GreenXenith> "confusing" is not specific 03:09 MTDiscord <Jonathon> apicall(pos: vector) . it is rather confusing i would think to a new person with a tiny bit of experience as there going to look at that and say, ok i see (), the things inside of it must be the arguements you pass to it, and having two there will through them off 03:10 MTDiscord <Benrob0329> Hmm, I'm not sure that using the same name as the namespace is a good idea 03:10 MTDiscord <Jonathon> additonally it has a : which the api call is using 03:10 MTDiscord <GreenXenith> Using a generic term is worse 03:10 MTDiscord <Jonathon> i thiunk documenting the type is fine, just not in that from 03:10 MTDiscord <Jonathon> not that i can think of a better form atm 03:11 MTDiscord <GreenXenith> the prerequisite to reading this document is knowing basic Lua, and people that know basic lua know that arguments are not typed and are separated by commas, not colons 03:11 MTDiscord <GreenXenith> param: type is a very common syntax 03:11 MTDiscord <GreenXenith> better than C-style type param 03:12 MTDiscord <Benrob0329> I do understand wsor's concern here, but I'm not sure there's a better way to do it 03:12 MTDiscord <GreenXenith> Feel free to hash it out, gotta run for a few hours 03:12 MTDiscord <Benrob0329> The bullet list works too, but using that for non-type descriptions is nice 03:13 MTDiscord <Jonathon> maybe could use the @ symbol nicely somehow as some documentation standards uses for the params 03:13 MTDiscord <Benrob0329> That doesn't sound any clearer 03:15 MTDiscord <GreenXenith> This is the sort of thing that can be clarified with theming 03:15 MTDiscord <Benrob0329> How likely do we think that it is for a new person to actually get confused by this? 03:15 MTDiscord <Benrob0329> I have an idea, follow me to #general 03:22 MTDiscord <Benrob0329> Fatal got it, though he shared wsors sentiment 03:23 MTDiscord <Benrob0329> Seems to me like it's clear enough, the only alternative I can think if is to push it into the bullet list 03:23 MTDiscord <Jonathon> honestly, i think working it into the bullet is better 03:24 MTDiscord <Jonathon> can you work tooltips or anything fancy into asciidocs? 03:25 MTDiscord <Benrob0329> Possibly, though I'm not certain since that wouldn't always translate nice to all formats 03:25 MTDiscord <Jonathon> yeah... 03:25 MTDiscord <Jonathon> seems #general agrees putting it in bullet is better, just not how 03:28 MTDiscord <Jonathon> you could do it how the jest documentation does it 03:28 MTDiscord <Jonathon> https://cdn.discordapp.com/attachments/926231483155378176/928127818259386368/unknown.png 03:29 MTDiscord <Jonathon> or using the type to lead right into the description 03:29 MTDiscord <Jonathon> https://cdn.discordapp.com/attachments/926231483155378176/928128035977306152/unknown.png 03:31 MTDiscord <Benrob0329> asciidoc === Vehicle:set_pos(pos) * `pos`: xref:vector.adoc[`vector`] ** Position where the vehicle is placed. 03:32 MTDiscord <Jonathon> rendered 03:32 MTDiscord <Jonathon> https://cdn.discordapp.com/attachments/926231483155378176/928128783226110033/unknown.png 03:32 MTDiscord <Jonathon> my suggestion 03:32 MTDiscord <Jonathon> https://cdn.discordapp.com/attachments/926231483155378176/928128866399166474/unknown.png 03:33 MTDiscord <Benrob0329> Could also use a table: ``asciidoc === Vehicle:set_pos(pos) |=== pos | xref:vector.adoc[vector`] | Position where the Vehicle is placed |=== ```` 03:34 MTDiscord <Jonathon> doing this may make the document like 1/4 times longer tbh 03:34 MTDiscord <Benrob0329> Or the description list: asciidoc === Vehicle:set_pos(pos) `pos`: xref:vector.adoc[`vector`]:: Position where the vehicle is placed. 03:35 MTDiscord <Jonathon> this doesnt work 03:35 MTDiscord <Benrob0329> Oh wait 03:35 MTDiscord <Benrob0329> try now 03:36 MTDiscord <Jonathon> maybe if you can adjust the column sizing? rather large 03:36 MTDiscord <Benrob0329> You can 03:37 MTDiscord <Benrob0329> I just didn't here, one sec while I look up the syntax 03:37 MTDiscord <Jonathon> frick, fatal likes both for different reasons 03:37 MTDiscord <Benrob0329> updated the snippet 03:38 MTDiscord <Jonathon> thats worse 03:38 MTDiscord <Jonathon> i mean like moving the distribution of cells rather than size 03:38 MTDiscord <Jonathon> i.e. pos, vector are tiny in a huge column 03:38 MTDiscord <Benrob0329> oh there's an autowidth setting 03:38 MTDiscord <Jonathon> and then the description is jammed in a tiny area 03:39 MTDiscord <Benrob0329> try now 03:39 MTDiscord <Jonathon> much better 03:39 MTDiscord <Benrob0329> (post for posterity?) 03:39 MTDiscord <Jonathon> https://cdn.discordapp.com/attachments/926231483155378176/928130666623815730/unknown.png 03:40 MTDiscord <Jonathon> two im debating which i like better 03:40 MTDiscord <Benrob0329> We can change the table style too 03:40 MTDiscord <Jonathon> in html 03:40 MTDiscord <Benrob0329> remove the grid lines or borders 03:40 MTDiscord <Benrob0329> In asciidoc 03:41 MTDiscord <Benrob0329> This can differ from table to table, and is used across different formats 03:41 MTDiscord <Jonathon> why is pos and vector so bloody small tho? 03:41 MTDiscord <Jonathon> just noticed that 03:41 MTDiscord <Benrob0329> probably because they're both monospaced and inside the table 03:41 MTDiscord <Jonathon> its like 1/2 or 3/4 size of description 03:41 MTDiscord <Benrob0329> switch from VSCode style to AsciiDoctor style in the extension 03:42 MTDiscord <Benrob0329> that might help 03:42 MTDiscord <Benrob0329> But this is just the template's CSS, ie something that is fixed in the HTML side 03:43 MTDiscord <Benrob0329> The thing I don't like with tables is that it's syntax heavy 03:43 MTDiscord <Jonathon> yeah, ninjad me 03:43 MTDiscord <Benrob0329> and not really more readable 03:43 MTDiscord <Jonathon> for that reason id opt more for the top half 03:43 MTDiscord <Benrob0329> What do you think of the descriptor list? 03:44 MTDiscord <Jonathon> descriptor list? 03:44 MTDiscord <Jonathon> non rendered vs rendered 03:44 MTDiscord <Jonathon> https://cdn.discordapp.com/attachments/926231483155378176/928131877494222948/unknown.png 03:45 MTDiscord <Jonathon> adoc === Vehicle:set_pos(pos) `pos`: xref:vector.adoc[`vector`]:: Position where the vehicle is placed. that? 03:45 MTDiscord <Benrob0329> Yes 03:46 MTDiscord <Jonathon> i think that its more confusing syntax to save a line. not only that if viewing raw via nano its not as understandable as two lines 03:47 MTDiscord <Jonathon> adoc === Vehicle:set_pos(pos) * `pos`: xref:vector.adoc[`vector`] - Position where the vehicle is placed. being better 03:47 MTDiscord <Jonathon> im not sure however when you start doing multiples 03:48 MTDiscord <Jonathon> i think i favor adoc === Vehicle:set_pos(pos) * `pos`: xref:vector.adoc[`vector`] Position where the vehicle is placed. most tbh, with your descriptor list probably second, and then * - method third 03:48 MTDiscord <Jonathon> mainly descriptor second because of multiple arguements 03:48 MTDiscord <Jonathon> if that makes sense? 03:50 MTDiscord <Jonathon> what is your personal opinion benrob? 03:51 MTDiscord <Benrob0329> I'm pretty sure you can split descriptor lists into multiple lines 03:51 MTDiscord <Benrob0329> I'm more wondering about what you think of it rendered 03:52 MTDiscord <Benrob0329> (I'd post a screenshot but I'm afk right this second) 03:53 MTDiscord <Jonathon> its not going to break my heart if we decide 2 line rendered is better, i just think reading raw text wise the discriptor is better than * - mess 04:18 MTDiscord <Benrob0329> Some options: 04:18 MTDiscord <Benrob0329> https://cdn.discordapp.com/attachments/926231483155378176/928140414685417492/unknown.png 04:19 MTDiscord <Benrob0329> Some options: 04:19 MTDiscord <Benrob0329> https://cdn.discordapp.com/attachments/926231483155378176/928140587524296794/unknown.png 05:32 MTDiscord <GreenXenith> Is there an alternative to the online type but without parentheses? (Not table) 05:32 MTDiscord <GreenXenith> (Still not back yet) 05:32 MTDiscord <GreenXenith> Inline* 06:02 MTDiscord <Benrob0329> The 2nd one I posted? Yeah, we could do a lot of different punctuation. 06:02 MTDiscord <Benrob0329> For example: * pos: vector, Position where the vehicle is placed. 06:03 MTDiscord <Benrob0329> I think that allowing multiple lines for arguments might be a good idea for when there is inevitably a non-trivial argument 08:08 MTDiscord <GreenXenith> I am still a strong proponent of in-function types 08:08 MTDiscord <GreenXenith> https://cdn.discordapp.com/attachments/926231483155378176/928198310701985872/unknown.png 08:09 MTDiscord <GreenXenith> in-function is quicker to read at a glance and takes up less space 08:10 MTDiscord <GreenXenith> Most documentation worth its salt does in-function types, and it doesnt take much time to get used to if youre new to it. May as well get the newbies to learn the standard anyway. 08:11 MTDiscord <GreenXenith> fatalerror understood it just fine, so far no one has actually had an issue with it themselves, only the possible notion that some beginner might get confused 08:11 MTDiscord <GreenXenith> I dont consider that enough reason to not use in-function notation 08:39 MTDiscord <GreenXenith> Here's a sort of LOVE-style documentation, but it is still not very easy to read, and its style-dependent (links are for styling, not linking) 08:39 MTDiscord <GreenXenith> https://cdn.discordapp.com/attachments/926231483155378176/928206118021365760/unknown.png 09:09 MTDiscord <GreenXenith> The original style with the longest function in the API 09:09 MTDiscord <GreenXenith> https://cdn.discordapp.com/attachments/926231483155378176/928213511518175282/unknown.png 09:29 MTDiscord <GreenXenith> Scratch that, found an even longer one 09:29 MTDiscord <GreenXenith> https://cdn.discordapp.com/attachments/926231483155378176/928218602698600458/unknown.png 09:38 MTDiscord <GreenXenith> it also kinda depends on how big the headers get rendered. Really they shouldnt be much bigger than normal text. 09:38 MTDiscord <GreenXenith> https://cdn.discordapp.com/attachments/926231483155378176/928220841945206804/unknown.png 09:39 MTDiscord <GreenXenith> This is a complex issue ? 10:35 MTDiscord <luatic> I much like Warr's <dl> proposal BTW. Why don't we document params using "param:: description" instead of "* param: description"? Or maybe even a table? Or maybe even a table? This is how LÖVR does it at least. 10:35 MTDiscord <luatic> https://cdn.discordapp.com/attachments/926231483155378176/928235328530153532/Bildschirmfoto_von_2022-01-05_11-35-22.png 11:01 MTDiscord <GreenXenith> thats a ridiculous amount of space for one function 11:09 MTDiscord <GreenXenith> @Luatic in the future, please use a less passive-aggressive tone in reviews, its annoying and unhelpful. Just say "vehicle should be uppercase", not "How did the Vehicle go lowercase?" or "This is redundant" instead of "Stating the obvious?" 12:27 MTDiscord <exe_virus> Fair that is a lot of space used. I don't mind though for the reference sections if the function takes the whole screen, as long we have quick sidebar nav that lets us click to a list of anchors on the page. 12:27 MTDiscord <exe_virus> For examples and other sections where learning is occuring, that should be a lot tighter to allow a person to cross reference sentences quickly 13:50 MTDiscord <Sublayer plank> ohh so that's how you make table source not look absolutely abysmal, markdown ruined me with its table syntax :P 14:31 MTDiscord <Benrob0329> Yeah, MD-style ascii-art tables are..ehh 15:02 MTDiscord <josiah_wi> That was pinned accidentally. My UI is in German and I was in a hurry and did not realise I was pinning it. 15:03 MTDiscord <josiah_wi> I could not have picked a better link to accidentally pin, though. 15:39 MTDiscord <Benrob0329> @Luatic The "Global Functions" section is meant to demonstrate how to document global functions 15:39 MTDiscord <Benrob0329> Its not a mistake or a miswording 16:32 MTDiscord <j45> >What does "step up" mean if I'm not familiar with engine terminology? literally how high the object can step 16:33 MTDiscord <luatic> Well, define "step" 16:33 MTDiscord <luatic> I'm struggling to come up with a clean definition, what I have in mind is way too technical 16:34 MTDiscord <luatic> Basically, when the object would be blocked by a front- or side-face (non-top and non-bottom), this is how high - in nodes - the object will teleport up to step on the collisionbox instead 16:35 MTDiscord <luatic> The player uses this when climbing stairs, for example. But there it is at least smoothed. 16:35 MTDiscord <luatic> (the movement of the camera is smoothed) 16:37 MTDiscord <josiah_wi> "How many nodes the object can climb in one step."? 16:37 MTDiscord <josiah_wi> can climb at a time* 16:38 MTDiscord <luatic> no 16:38 MTDiscord <josiah_wi> I guess technically it could climb half a node. ? 16:38 MTDiscord <luatic> this is not how stepheight works 16:38 MTDiscord <luatic> first of all it isn't tied to nodes but collisionboxes AFAIK (or so I hope) 16:39 MTDiscord <luatic> second the "many" is misleading, this is in "in-game metres" / nodes as a unit, but it's not like you could climb 10 nodes using this 16:39 MTDiscord <luatic> and finally the "climbing" part is misleading as well, this literally just teleports you up when you run into something 16:39 MTDiscord <josiah_wi> So "how high the object can step up to get on top of another object" would make sense. 16:40 MTDiscord <luatic> that sounds well, but to get on top of another collisionbox, be it from a node or an object 16:40 MTDiscord <josiah_wi> Followed by a technical detail about collisionboxes. 16:40 MTDiscord <luatic> our terminology gets mushy again 16:40 MTDiscord <josiah_wi> it sounds good, or it flows well. ? 16:40 MTDiscord <luatic> XOR it seems xD 16:41 MTDiscord <luatic> How do we distinguish 1. objects as in objects of classes 2. ObjectRefs specifically 3. in-game objects, like objectrefs and nodes 16:41 MTDiscord <luatic> or even 4. just objects 16:42 MTDiscord <luatic> we need to start a terminology.adoc it's not like I have done this already 16:48 MTDiscord <luatic> https://github.com/minetest/minetest_docs/pull/21 17:06 MTDiscord <Benrob0329> Well, entities are objects with methods, as are vectors, and many other objects. Entities are objects within the map, though, and not just in code. 17:11 MTDiscord <Benrob0329> As for step_height, maybe "This sets the maximum height (in nodes) that an entity can travel up if it collides with something. This allows it to "step" over obstacles and continue traveling." 17:12 MTDiscord <Benrob0329> Remember that ObjRef is a technical term for a literal object reference which points to an entity, and despite lua_api's poor choice of terminology is not the name of the actual thing it points to. 17:13 MTDiscord <Benrob0329> At best it could be called a Server Active Object, but entity is whats actually used by the registration function. 17:14 MTDiscord <j45> phew, i fucked up with git but i fixed it 17:14 MTDiscord <Benrob0329> How so and how so? 17:16 MTDiscord <j45> i did git pull which unexpectantly pulled from minetest_docs, instead of my own fork's branch (i wanted to pull luatic's change)... but i fixed with git reset --hard 795ad2e which restores it to the state of the commit 795ad2e, which was what i was on before i fucked up 17:16 MTDiscord <Benrob0329> Fair enough 17:17 MTDiscord <Benrob0329> Yeah, you generally want to work out of your own fork rather than from the main repo's upstream 17:18 MTDiscord <j45> ya... 17:29 MTDiscord <j45> huh? why didnt this work? atleast i know how to fix it now lol 17:29 MTDiscord <j45> https://cdn.discordapp.com/attachments/926231483155378176/928339380987387934/unknown.png 17:29 MTDiscord <j45> OH im not being stupid 17:30 MTDiscord <j45> Luatic did this 17:30 MTDiscord <j45> https://github.com/Minetest-j45/minetest_docs/commit/0ba800583f2b4a9b5d72bda412beb9473f79027a 17:30 MTDiscord <j45> jk, its fine 17:38 MTDiscord <josiah_wi> Thank you for merging instead of rebasing. This is an example of where rebasing would cause a lot of problems. 21:57 MTDiscord <GreenXenith> not a huge fan 21:57 MTDiscord <GreenXenith> https://cdn.discordapp.com/attachments/926231483155378176/928406796815695902/unknown.png 21:59 MTDiscord <luatic> I am a fan 22:00 MTDiscord <luatic> Should be success = vehicle.new(pos, properties) 22:04 MTDiscord <Benrob0329> My vote absolutely goes for using -> for return types, you return a lot less than you pass arguments 22:04 MTDiscord <luatic> Return values probably shouldn't be named ?, just numbered (maybe an ordered list is the proper thing to use here) 22:04 MTDiscord <Benrob0329> an arrow is pretty clear IMO and doesn't take up much space 22:04 MTDiscord <luatic> Only documents the types tho, the actual value is documented in prose then. 22:05 MTDiscord <Benrob0329> right, we're going to have prose anyways 22:05 MTDiscord <luatic> I also like it if pretty much everything monospaced is valid Lua 22:05 MTDiscord <luatic> the arrow breaks with that 22:05 MTDiscord <Benrob0329> the arrow can be not-monospaced 22:06 MTDiscord <Benrob0329> asciidoc === `mything.function(foo, bar)` -> `string` 22:07 MTDiscord <luatic> ADoc will even turn that into a nice "→" 22:07 MTDiscord <Benrob0329> yes 22:07 MTDiscord <luatic> Still kinda odd that we document namespace.funcname(argnames) -> returnTYPE 22:07 MTDiscord <Benrob0329> you usually only return 1 thing, sometimes 2, and rarely 3 22:08 MTDiscord <Benrob0329> so just the type is fine IMO 22:09 MTDiscord <GreenXenith> still not a fan 22:09 MTDiscord <GreenXenith> https://cdn.discordapp.com/attachments/926231483155378176/928409951439831101/unknown.png 22:10 MTDiscord <luatic> Minimum redundancy would be the following: asciidoc == `mything` === `function` Functions. ==== Arguments . `foo`: `string`. Name of the foo. . `bar`: `number`. How many times it should function. ==== Return values . `vector`. Position the foo was spawned at. 22:10 MTDiscord <Benrob0329> This feel way too technical for something meant to be explaining thing in plain English 22:11 MTDiscord <luatic> What about a definition list? 22:11 MTDiscord <luatic> https://cdn.discordapp.com/attachments/926231483155378176/928410306336673812/Bildschirmfoto_von_2022-01-05_23-10-41.png 22:11 MTDiscord <GreenXenith> Its the existing API reference, im just using it for style testing because of its size 22:11 MTDiscord <Benrob0329> Still 22:11 MTDiscord <GreenXenith> If you mean the table makes it feel too technical, then yeah I see it 22:12 MTDiscord <luatic> The table forces you to cleanly separate everything though. 22:12 erlehmann GreenXenith did you autogenerate that? 22:12 MTDiscord <GreenXenith> No? 22:12 MTDiscord <luatic> I assume he used either AsciiDoctor or a preview plugin for his editor of choice. 22:13 MTDiscord <GreenXenith> re: definition list; So, LOVE-style instead of LOVR-style? ? 22:13 MTDiscord <luatic> I guess so 22:14 erlehmann i have a question, how to handle the types where the function has a narrower type than the actual data type 22:14 MTDiscord <luatic> Prose 22:14 MTDiscord <Benrob0329> I like the definition list, I think it's clearer than a bullet list but cleaner than the table 22:15 MTDiscord <GreenXenith> To be clear, we will probably never find a format that handles functions like place_schematic_on_vmanip very well 22:15 MTDiscord <luatic> So, (ordered) list, definition list, or table? 22:15 MTDiscord <GreenXenith> I still need to test the list version 22:15 MTDiscord <GreenXenith> but the type should really go on the name line 22:15 MTDiscord <Benrob0329> Also, type in the description or the list header? 22:16 MTDiscord <GreenXenith> ? 22:16 MTDiscord <luatic> asciidoc == `vehicle.new` Spawns a new vehicle. [source,lua] ---- success = vehicle.new(pos, properties) ---- === Arguments `pos`:: https://example.com[`vector`]. The position to spawn the vehicle at. `properties`:: https://example.com[`Vehicle properties`] === Return value `success`:: `bool`. Whether the placement was successfull. 22:16 erlehmann i like the definition list too, but if i am not mistaken, it should be able to record these things in a way that we can change how it is rendered later right? 22:16 MTDiscord <Benrob0329> ie: asciidoc pos: vector:: Foo pos:: vector, foo 22:16 erlehmann luatic i saw that all on one line 22:16 erlehmann luatic was that intended? 22:16 MTDiscord <luatic> erlehmann: not really, I assumed the bridge was more capable 22:17 MTDiscord <Benrob0329> blame the bridge, someone could gist it I suppose 22:17 MTDiscord <GreenXenith> bridge doesnt support replies or multiline afaik 22:17 MTDiscord <luatic> The choice of AsciiDoc couples our docs to certain formatting unfortunately 22:17 MTDiscord <luatic> A DSL would be better here ? 22:18 MTDiscord <Benrob0329> We can change styling later, but the thing used should be decided now 22:18 MTDiscord <GreenXenith> as long as styling is consistent, scripting style changes is pretty easy 22:18 MTDiscord <Benrob0329> also that 22:19 erlehmann you know what: if you have a table, i bet i can style it like a numbered list or definition list 22:19 erlehmann give me a few minutes 22:19 MTDiscord <Benrob0329> hold on, let me find the screenshot 22:19 MTDiscord <Benrob0329> we have talked about this 22:20 MTDiscord <Benrob0329> https://cdn.discordapp.com/attachments/926231483155378176/928412739217526814/unknown.png 22:20 MTDiscord <Benrob0329> last one is a table 22:21 erlehmann last one looks nice 22:22 MTDiscord <Benrob0329> setting the default table style would be nice 22:23 MTDiscord <GreenXenith> still dont like it 22:23 MTDiscord <GreenXenith> https://cdn.discordapp.com/attachments/926231483155378176/928413409735766027/unknown.png 22:24 MTDiscord <Benrob0329> @GreenXenith How does the less-noisy table look? 22:24 MTDiscord <Benrob0329> the style I put in the screenshot I sent 22:24 MTDiscord <Benrob0329> ie no header no frame 22:25 MTDiscord <GreenXenith> https://cdn.discordapp.com/attachments/926231483155378176/928413910325948476/unknown.png 22:26 MTDiscord <Benrob0329> honestly, better 22:26 MTDiscord <GreenXenith> better than the first table at least 22:26 MTDiscord <GreenXenith> I still really dont like how long this takes to read 22:26 MTDiscord <Benrob0329> it is is a big function 22:27 MTDiscord <GreenXenith> I mean, with the original style I can look at the header and have 80% of the information I want 22:27 MTDiscord <GreenXenith> er, thats a bad way to put it. I have all of the information I need, and I only need the body if Im reading it for the first time or need a detail 22:28 MTDiscord <Benrob0329> put the body below the arguments 22:29 MTDiscord <Benrob0329> I will say, I don't support having a seperate return list, I think it's more long-winded than ever needed since the function needs to be described in prose anyways. 22:29 MTDiscord <Benrob0329> I think that having a good one-liner for what it returns at the start of the body is best 22:30 MTDiscord <GreenXenith> maybe we can make a hybrid of this 22:30 MTDiscord <Benrob0329> But I'm not sure if I've missed some discussion about it 22:31 erlehmann just to prove that a table can definitely be styled as a list (look at the markup) https://mister-muffin.de/p/_Yv8.html 22:33 erlehmann and yes i have left out a lot of stuff that is not needed ;) 22:33 erlehmann tables in html are full of unwelcome surprises 22:33 erlehmann who knows about thead and tbody anyway 22:33 erlehmann or caption 22:34 erlehmann this is unfortunate 22:37 MTDiscord <GreenXenith> ok, ew 22:38 MTDiscord <GreenXenith> some functions return different amounts of values depending on the input 22:38 MTDiscord <Benrob0329> Yup 22:41 MTDiscord <GreenXenith> how are we supposed to handle that 22:41 MTDiscord <GreenXenith> specifically in this case, its not just different amounts, the meaning of each value is different too 22:42 MTDiscord <luatic> case distinction 22:42 MTDiscord <luatic> perhaps even treat it like two entirely different calls ? 22:42 MTDiscord <GreenXenith> This project is just going to make me hate Minetest more than I already do and make me begin to hate Lua :D 22:43 MTDiscord <luatic> unfortunately yes 22:43 MTDiscord <luatic> multiple return values are overused 22:43 MTDiscord <GreenXenith> multiple return values are fine ... when used consistently 22:43 MTDiscord <luatic> sometimes a table should just be used ffs 22:46 MTDiscord <GreenXenith> I do not like it, Sam I Am 22:46 MTDiscord <GreenXenith> https://cdn.discordapp.com/attachments/926231483155378176/928419158461386752/unknown.png 22:47 MTDiscord <luatic> I think it's fine 22:47 MTDiscord <Benrob0329> I liked what I did with the definition table for vector, so here I am shilling it again 22:48 MTDiscord <Benrob0329> *definition list 22:48 MTDiscord <Benrob0329> Or descriptor list 22:48 MTDiscord <GreenXenith> yeah, vector doesnt have a def table ;p 22:50 MTDiscord <Benrob0329> You can have multiple lines in a d-list too 22:50 MTDiscord <GreenXenith> the one thing I dont like about the vector doc and what I do like about these styles is the return value is not documented in english, making it easier to parse 22:50 MTDiscord <Benrob0329> So a longer bit of prose for a given return is entirely doable 22:51 MTDiscord <Benrob0329> I also have the return type in the header 22:51 MTDiscord <GreenXenith> (s/english/prose) 22:51 MTDiscord <Benrob0329> Just not it's explanation 22:52 MTDiscord <GreenXenith> well your header style was proven problematic on longer functions 22:52 MTDiscord <Benrob0329> Fair 22:52 MTDiscord <GreenXenith> and completely broken for stuff that can have varying return amounts/types 22:52 MTDiscord <Benrob0329> I'd argue that 22:53 MTDiscord <GreenXenith> (how do you represent "(nodes) or (positions, totals)" in your header style?) 22:54 MTDiscord <Benrob0329> You can do asciidoc === `myfoo(bla, bar)` -> `node` or `vector, number` 22:54 erlehmann question: is the real problem maybe that the function interfaces are not already documented in a machine readable way? 22:54 erlehmann if they were, like in typescript or typed python, it would be easy to generate all that info 22:54 MTDiscord <luatic> kind of 22:54 MTDiscord <GreenXenith> You missed the DSL discussion 22:55 erlehmann could be. lua needs a dsl for that? 22:55 MTDiscord <luatic> Something LuaDoc-ish would be nice 22:55 MTDiscord <luatic> Lua can be used to implement a DSL for that 22:55 MTDiscord <Benrob0329> Our main issue here is human readability 22:55 MTDiscord <Benrob0329> Machine readability is secondary to that IMO 22:55 MTDiscord <GreenXenith> I blame Minetest for stupid design 22:55 erlehmann machine readability can make human readability easier 22:56 erlehmann GreenXenith you are prob not alone with that ^^ 22:56 MTDiscord <GreenXenith> inconsistent return values and too many arguments are Minetest fault, we shouldnt have to work around it >:/ 22:56 erlehmann take our friend minetest.find_nodes_in_area() 22:56 erlehmann multiple ways to invoke it, multiple ways to return stuff 22:56 MTDiscord <Benrob0329> Aa good description is not very machine readable but can help human readability a lot 22:57 MTDiscord <Benrob0329> And in the end, to what extent do these need to be machine readable? What actually needs to be parsed? 22:57 MTDiscord <GreenXenith> function names, arguments, types, return values 22:57 MTDiscord <Benrob0329> OK, so mainly the types 22:58 MTDiscord <GreenXenith> thats most of it yeah 22:58 MTDiscord <Benrob0329> I think we can manage that if we're willing to agree that huge functions suck anyways 22:58 erlehmann we can agree on that, but we have those 22:58 erlehmann and they need docs 22:58 MTDiscord <GreenXenith> solution: submit PRs to the engine to fix the functions :D 22:59 MTDiscord <Benrob0329> We do, so we'll do the best we can but it won't be perfect 22:59 MTDiscord <Benrob0329> Its ok to not be perfect everywhere, just good enough 22:59 erlehmann my approach would be to document the function several times under several headers 22:59 MTDiscord <GreenXenith> huge functions suck but we can work with them. But stupid return values suck more and are harder to work with 22:59 erlehmann like foo(bar) then a table for the returns, then foo(bar, baz), then a table for the returns etc. 23:00 MTDiscord <GreenXenith> the term is overloads 23:01 MTDiscord <GreenXenith> and its certainly a possibility 23:01 MTDiscord <Benrob0329> Treating it like overloads would work 23:02 MTDiscord <GreenXenith> I will grant this: LOVER-style documentation is dirt simple to machine parse 23:04 MTDiscord <GreenXenith> Hm, erlehmann may have a good point about machine-readability improving human-readability 23:08 MTDiscord <Benrob0329> I can feel it, coming in the air tonight, oh Looord. I've been running from this moment, for all my life, oh Looord, oh Lord 23:09 MTDiscord <Benrob0329> If we make a DSL it'll be more things to bikeshed 23:09 MTDiscord <GreenXenith> oh im not talking about DSL 23:09 MTDiscord <Benrob0329> Oh? 23:10 MTDiscord <GreenXenith> Im just trying looking at it from the perspective of the machine 23:10 MTDiscord <Benrob0329> Alright 23:10 MTDiscord <GreenXenith> https://cdn.discordapp.com/attachments/926231483155378176/928425167250661386/unknown.png 23:10 MTDiscord <GreenXenith> This is human readable and machine readable without having extra sections 23:10 MTDiscord <Benrob0329> I can live with that 23:11 MTDiscord <GreenXenith> the only thing it could use is labels on the overloads -> returns 23:11 erlehmann GreenXenith could you also mockup my variant where the heading is the function with the arguments? 23:11 MTDiscord <Benrob0329> Seems readable and shouldn't be terrible to write 23:11 erlehmann because this way it is not clear when it returns what 23:11 MTDiscord <GreenXenith> We've done the heading with arguments before 23:11 MTDiscord <GreenXenith> and with types 23:11 MTDiscord <GreenXenith> and with returns 23:11 erlehmann oh ok show 23:11 erlehmann pls 23:11 erlehmann i missed it it seems 23:11 MTDiscord <GreenXenith> it .. was literally in the shot ben posted 23:11 Desour btw. what's the main reason why you don't use luadoc? 23:12 MTDiscord <Benrob0329> Isn't Luadoc for embedded documentation? 23:12 MTDiscord <Benrob0329> And also, isn't it barely maintained? 23:13 MTDiscord <Benrob0329> Anyways, it is once again time for me to go make sure the mostly flightless birds are all alive and well 23:13 MTDiscord <Benrob0329> So bbiab 23:13 MTDiscord <GreenXenith> https://cdn.discordapp.com/attachments/926231483155378176/928425992681316402/unknown.png 23:14 erlehmann GreenXenith oh well it has no tables. i like your stuff more in the end. 23:14 erlehmann regardless, i'll sit back and wait 23:14 erlehmann hmm no 23:14 MTDiscord <GreenXenith> Those were focusing more on the header part, like you asked 23:14 erlehmann hmmmm 23:15 MTDiscord <GreenXenith> they can be combined with a table instead of a list, but there are fundamental issues with arguments/returns in the header 23:15 erlehmann ok so what i had in mind was doing it exactly like you did but treating them as separate functions and not having the return type in the header 23:15 MTDiscord <GreenXenith> see: find_nodes_in_area 23:15 erlehmann only arguments in the header, not returns 23:15 erlehmann so basically foo with 2 arguments would be documented separately from foo with 3 arguments 23:15 erlehmann like they were separate functios 23:15 erlehmann functions 23:15 MTDiscord <GreenXenith> Yes, you already said that 23:16 MTDiscord <GreenXenith> its called overloading 23:16 erlehmann the thing is, i think having the return types in the header is superfluous 23:16 MTDiscord <GreenXenith> But it would be nice to avoid having to document overloading 23:16 erlehmann because you are often looking by argument type, rarely by return type 23:16 erlehmann well *technically* those can be seen as two different functions under the hood 23:16 MTDiscord <GreenXenith> The return type is still useful information 23:17 MTDiscord <GreenXenith> I dont want to rehash this again 23:17 erlehmann yes but i would not put it in the header 23:17 erlehmann ok sorry 23:17 erlehmann i will be silent and wait what comes of it, then try to work with it 23:17 erlehmann pls ping me when you are done! 23:17 MTDiscord <GreenXenith> there are enough other issues with it that others wanted to try different styles 23:17 MTDiscord <GreenXenith> so thats what weve been doing 23:18 Desour > Isn't Luadoc for embedded documentation? you can also use it for non-embedded documentation via -- @function function_i_want_to_doc 23:21 Desour (at least it's possible in ldoc https://stevedonovan.github.io/ldoc/ ) 23:32 MTDiscord <Benrob0329> Anyways, I think I like the last style Green suggested (Name-only header, description, usage, arguments table[s], return table[s) 23:32 MTDiscord <GreenXenith> I wish I could put a number before the code block and tables 23:33 MTDiscord <GreenXenith> technically I could use another table but nesting tables is messy and not officially supported 23:33 MTDiscord <Benrob0329> it's officially supported 23:33 MTDiscord <GreenXenith> I couldnt get it tow ork 23:33 MTDiscord <Benrob0329> https://docs.asciidoctor.org/asciidoc/latest/tables/nested/ 23:33 MTDiscord <GreenXenith> also can you set all table lines to none 23:34 MTDiscord <Benrob0329> You use a different table deliminator 23:34 MTDiscord <GreenXenith> I tried that but it didnt want to work 23:34 MTDiscord <GreenXenith> looks like it requires [cols] or something 23:35 MTDiscord <Benrob0329> anyways, what do you mean put a number? Like to distinguish calls? 23:35 MTDiscord <GreenXenith> yeah, to match the overload to the return values 23:35 MTDiscord <GreenXenith> its implied by order but im not sure thats good enough 23:36 MTDiscord <Benrob0329> I'm trying to see what the AsciiDoctor docs use for the little numbered circles 23:40 MTDiscord <GreenXenith> the return table width isnt right but basically this 23:40 MTDiscord <GreenXenith> https://cdn.discordapp.com/attachments/926231483155378176/928432818646843433/unknown.png 23:42 MTDiscord <GreenXenith> theyre probably just custom footnotes 23:42 MTDiscord <Benrob0329> Thats what I'm wondering 23:42 MTDiscord <Benrob0329> but it doesn't look like it 23:43 MTDiscord <Benrob0329> I don't actually see it, though I have an idea 23:45 MTDiscord <Benrob0329> This is the syntax they use, I'm not sure if it's specific or using something else: 23:45 MTDiscord <Benrob0329> https://cdn.discordapp.com/attachments/926231483155378176/928433982545219624/unknown.png 23:45 MTDiscord <Benrob0329> it works in vanilla AsciiDoctor though: 23:45 MTDiscord <Benrob0329> https://cdn.discordapp.com/attachments/926231483155378176/928434087759343686/unknown.png 23:46 MTDiscord <Benrob0329> Is it just an enumerated list? 23:46 MTDiscord <GreenXenith> looks like it, and it only works consecutively inside a single block 23:47 MTDiscord <Benrob0329> I can put a number in there instead 23:47 MTDiscord <GreenXenith> o? 23:47 MTDiscord <Benrob0329> this feels like a passthrough 23:47 MTDiscord <GreenXenith> This should work though 23:49 MTDiscord <Benrob0329> aha https://docs.asciidoctor.org/asciidoc/latest/verbatim/callouts/ 23:53 MTDiscord <GreenXenith> meh 23:53 MTDiscord <GreenXenith> cant seem to use it on the table very nicely 23:54 MTDiscord <Benrob0329> darn