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