| 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:00 |
|
MTDiscord joined #minetest-docs |
| 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:19 |
|
wsor joined #minetest-docs |
| 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?" |
| 11:23 |
|
appguru joined #minetest-docs |
| 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:39 |
|
appguru joined #minetest-docs |
| 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:32 |
|
ROllerozxa joined #minetest-docs |
| 15:32 |
|
wsor joined #minetest-docs |
| 15:32 |
|
MTDiscord joined #minetest-docs |
| 15:32 |
|
rubenwardy joined #minetest-docs |
| 15:33 |
|
BuckarooBanzai joined #minetest-docs |
| 15:33 |
|
Desour joined #minetest-docs |
| 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:24 |
|
appguru joined #minetest-docs |
| 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. |
| 18:10 |
|
erlehmann joined #minetest-docs |
| 18:26 |
|
appguru joined #minetest-docs |
| 19:12 |
|
erle joined #minetest-docs |
| 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:30 |
|
Desour joined #minetest-docs |
| 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:34 |
|
MTDiscord joined #minetest-docs |
| 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:45 |
|
Desour_ joined #minetest-docs |
| 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 |
