| Time |
Nick |
Message |
| 03:27 |
MTDiscord |
<exe_virus> Yep, links make life good |
| 04:20 |
|
MTDiscord joined #minetest-docs |
| 05:00 |
|
MTDiscord joined #minetest-docs |
| 09:03 |
|
erlehmann joined #minetest-docs |
| 09:28 |
|
erlehmann joined #minetest-docs |
| 10:30 |
|
erlehmann joined #minetest-docs |
| 11:00 |
|
erlehmann joined #minetest-docs |
| 11:06 |
|
appguru joined #minetest-docs |
| 11:12 |
|
erlehmann joined #minetest-docs |
| 11:22 |
|
erlehmann joined #minetest-docs |
| 11:30 |
|
appguru joined #minetest-docs |
| 11:56 |
|
appguru1 joined #minetest-docs |
| 13:41 |
|
erlehmann joined #minetest-docs |
| 17:24 |
MTDiscord |
<Benrob0329> @Minetest Docs Team I need a consensus on prose vs tables for internal type details like integer/decimal and bound ranges. |
| 17:25 |
MTDiscord |
<luatic> Integer is used so frequently that I'm against prose. |
| 17:25 |
MTDiscord |
<exe_virus> As long as the "thing" we're talking about is a link to it's description, I'm good. |
| 17:26 |
MTDiscord |
<exe_virus> I.e. integers link to the description of what an integer is |
| 17:26 |
MTDiscord |
<luatic> Exactly, that's the best solution. Same as for numbers etc. |
| 17:27 |
MTDiscord |
<exe_virus> Even better if we can make it a hoverable pop-up thing for the web-based render |
| 17:28 |
MTDiscord |
<josiah_wi> I am in favor of tables or a listing like in object_properties. |
| 17:28 |
MTDiscord |
<exe_virus> But yeah, beyond that tables always render better than prose |
| 17:28 |
MTDiscord |
<josiah_wi> Links to further documentation are a definite yay. |
| 17:28 |
MTDiscord |
<luatic> We should just have a document with the types. That would also supersede my "terminology" PR. |
| 17:29 |
MTDiscord |
<luatic> And that would be linked to. And after some time, we can expect our readers to have memorized what a "list" or "integer" actually is. |
| 17:30 |
MTDiscord |
<Benrob0329> I feel like Exe and Josiah are out of the loop, lemme go grab my laptop and write a better explanation of what specifically I'm talking about |
| 17:30 |
MTDiscord |
<josiah_wi> Yep, I am. |
| 17:33 |
MTDiscord |
<Benrob0329> Alright |
| 17:35 |
MTDiscord |
<Benrob0329> Continuing with our numerical example: Lua only has the number type, but a lot of functions in the API specifically take an integer or a decimal. LMD wants to list this either as the type, or in addition to the type since it's part of it. Green wants to specify it in prose, since it's not the actual type and is a part of the explanation anyways. |
| 17:38 |
MTDiscord |
<Benrob0329> It's roughly the difference between: asciidoc == mylib.function === Arguments | foo | number | integer (0-16) | The number of times X and: asciidoc == mylib.function === Arguments | foo | number | The number of times X. Must be an integer from 0-16. |
| 17:39 |
MTDiscord |
<luatic> If it's an integer, my proposal would be: | foo | integer | The number of times X. From 0 to 16, both inclusive. | |
| 17:39 |
MTDiscord |
<josiah_wi> I listed it as a separate type in object_properties which is what I prefer. |
| 17:39 |
MTDiscord |
<Benrob0329> It doesn't always matter what the underlying type is, because not all functions care and are bound well within practical limits (such as builtin functions that do just take a number), but sometimes it does matter and we need to agree-ish on how to do it. |
| 17:40 |
MTDiscord |
<josiah_wi> If it matters then a table will make that importance more obvious. |
| 17:41 |
MTDiscord |
<luatic> Well well, the problem is that the Lua API doesn't care too much. Sometimes it silently rounds or clamps; other times it throws errors, and sometimes it just goes up in flames. |
| 17:41 |
MTDiscord |
<luatic> The question is how much of that do we want to document? As I see it, we're focusing on best practice API usage. |
| 17:42 |
MTDiscord |
<Benrob0329> I personally think that we should try to always use terms that users are going to see, rather than those they aren't. They'll see number a lot, they probably won't see integer in actual code (this gets a bit muddier for objects, since they're actually tables or userdata but there too, users will see vector a lot in code). |
| 17:43 |
MTDiscord |
<josiah_wi> We should list best practice usage first and then have a section for advanced modders on the messy parts. We sort of already do that with our notes and cautions. |
| 17:43 |
MTDiscord |
<Benrob0329> So I absolutely want the type to be something that users will see, whether thats a class or raw type depends on the situation. |
| 17:43 |
MTDiscord |
<luatic> Well, users won't see "object properties" or "particle definition" as it's own type either |
| 17:43 |
MTDiscord |
<luatic> Yet we would document it as such |
| 17:44 |
MTDiscord |
<luatic> These are purely conceptually typedefs, as in fact Lua pretty much uses ducktyping |
| 17:44 |
MTDiscord |
<Benrob0329> Would we? I'd write that as type "table" and say what it is in the description. |
| 17:44 |
MTDiscord |
<luatic> Dangit we need a document on types as I said |
| 17:44 |
MTDiscord |
<Benrob0329> Because it is a properties table, not an object of it's own. |
| 17:44 |
MTDiscord |
<luatic> So is a vector (except it has a metatable too) |
| 17:45 |
MTDiscord |
<Benrob0329> "actual" objects are different, because they have further functionality than a normal table |
| 17:45 |
MTDiscord |
<Benrob0329> You don't instance a properties table, you just put values in it |
| 17:45 |
MTDiscord |
<luatic> Logically, these "properties" are kinda "data structs", and thus their own type |
| 17:45 |
MTDiscord |
<Benrob0329> It's not an object |
| 17:45 |
MTDiscord |
<luatic> Vectors can be used the same way |
| 17:45 |
MTDiscord |
<Benrob0329> They shouldn't be |
| 17:46 |
MTDiscord |
<Benrob0329> They used to be, but that's not current |
| 17:46 |
MTDiscord |
<luatic> Yet you would say minetest.get_node takes a vector, simply because vectors have been conceptually established as a "type" |
| 17:46 |
MTDiscord |
<luatic> It also makes docs much nicer to write |
| 17:46 |
MTDiscord |
<josiah_wi> We should just save the IRC log and upload it as the advanced usage docs. |
| 17:46 |
MTDiscord |
<Benrob0329> If properties tables are a type, then is every table argument it's own type? |
| 17:47 |
MTDiscord |
<Benrob0329> Legitimate question |
| 17:47 |
MTDiscord |
<luatic> In principle yes |
| 17:47 |
MTDiscord |
<luatic> But the main purpose of defining types is deduplication |
| 17:48 |
MTDiscord |
<Benrob0329> Because node tables have a standard form, property tables each have a standard form, schematic tables have a standard form, etc |
| 17:48 |
MTDiscord |
<luatic> Yeah. I'd definitely "define" ducktypes for those. |
| 17:49 |
MTDiscord |
<Benrob0329> But then, users are likely to actually encounter the terms "node", "schematic", and "properties". "integer" not so much |
| 17:49 |
MTDiscord |
<luatic> Mapnode: Table with fields name, param, param2. Node Definition: Table with lots and lots of fields. |
| 17:49 |
MTDiscord |
<Jonathon> seems you need to draw the line between use node (table with 3 values) and vector (table with 3 values and a metatable) and stuff like register_node tables |
| 17:49 |
MTDiscord |
<luatic> Why draw a line? All of these are ducktypes. |
| 17:49 |
MTDiscord |
<josiah_wi> Can we have a notation like "type: table (NodeDef[url])" |
| 17:50 |
MTDiscord |
<Benrob0329> Whether a function takes a whole number or not, within a range or not, and how it clamps that (if at all) feels like details and not type info to me. |
| 17:51 |
MTDiscord |
<Benrob0329> It's why the details field it there |
| 17:51 |
MTDiscord |
<Benrob0329> But we also have psudotypes like param2 |
| 17:51 |
MTDiscord |
<luatic> "Whole number or not" is considered a type by many languages. |
| 17:52 |
MTDiscord |
<Benrob0329> But not Lua |
| 17:52 |
MTDiscord |
<Benrob0329> Not 5.1, anyways |
| 17:52 |
MTDiscord |
<luatic> You stole my nitpick |
| 17:52 |
MTDiscord |
<Benrob0329> ninja'ed :P |
| 17:52 |
MTDiscord |
<Benrob0329> param2 is a psudotype, but is also easily stated in the description |
| 17:53 |
MTDiscord |
<Benrob0329> If we make the types whatever, and not the technical type, then I feel like that might be inconsistent and make it harder to machine parse |
| 17:54 |
MTDiscord |
<Benrob0329> But if it's always the technical type, then that's unhelpful in some cases |
| 17:54 |
MTDiscord |
<Benrob0329> "userdata" doesn't mean anything on it's own, for example |
| 17:54 |
MTDiscord |
<Benrob0329> But knowing something is "userdata" is helpful |
| 17:56 |
MTDiscord |
<Benrob0329> Ok, opinions on the rule of thumb that "Documentation should use terms which the user is most likely to encounter when working with the engine." |
| 17:57 |
MTDiscord |
<Benrob0329> we need to start working on an agreed upon baseline |
| 17:57 |
MTDiscord |
<josiah_wi> I don't think anybody will agree with that as you phrased it. |
| 17:58 |
MTDiscord |
<josiah_wi> I would agree that modders should be informed of engine behavior when not knowing it could cause problems for them. |
| 17:58 |
MTDiscord |
<josiah_wi> And only in those cases. |
| 17:59 |
MTDiscord |
<Benrob0329> I..what? |
| 17:59 |
MTDiscord |
<Benrob0329> I don't understand what I'm supposed to glean from that |
| 17:59 |
MTDiscord |
<luatic> The data types the Lua API uses are of course only the basic Lua ones - boolean, number, string, table, userdata, function |
| 18:00 |
MTDiscord |
<luatic> (and nil OFC) |
| 18:00 |
MTDiscord |
<luatic> There's little to add to boolean |
| 18:00 |
MTDiscord |
<luatic> Numbers might integers. It must be made clear that by this we just mean an integer Lua number. |
| 18:01 |
MTDiscord |
<luatic> Calling things tables is very problematic IMO. Tables are all-in-one - lists (also stacks and queues), sets or maps (called a "dictionairy" if the keys are strings). |
| 18:02 |
MTDiscord |
<Benrob0329> *dictionary :troll: |
| 18:03 |
MTDiscord |
<Benrob0329> This does not mean only use type(x), take it at face value please |
| 18:04 |
MTDiscord |
<luatic> The definition of table/number/string-based types would mention the internal Lua types. |
| 18:04 |
MTDiscord |
<luatic> +userdata |
| 18:04 |
MTDiscord |
<luatic> So we'd have: Integer: A Lua number with a remainder of zero. |
| 18:05 |
MTDiscord |
<luatic> Node: A table with fields ... |
| 18:06 |
MTDiscord |
<Benrob0329> Let me rephrase my question. I'd like to figure out what we agree on so that we don't argue things that don't need to be argued. Can we all agree that the docs should try to use terms people will see when working with code? |
| 18:06 |
MTDiscord |
<luatic> It should use them, but where? |
| 18:06 |
MTDiscord |
<luatic> I'm arguing that it might be "around the corner" through a "type definition" |
| 18:07 |
MTDiscord |
<luatic> The tables used by the myriads of node functions are actually a decent example |
| 18:07 |
MTDiscord |
<Benrob0329> I'm not talking about just using the term "table" |
| 18:07 |
MTDiscord |
<Benrob0329> Again, take it at face value. |
| 18:07 |
MTDiscord |
<luatic> Would you want to read & write "table (MapNode)" |
| 18:08 |
MTDiscord |
<luatic> This is just one specific example. But as said, the internal types must be mentioned, the question is just - must they be directly mentioned? |
| 18:08 |
MTDiscord |
<Benrob0329> I'm not talking about internal types specifically |
| 18:08 |
MTDiscord |
<luatic> But internal types are what the user is going to see |
| 18:08 |
MTDiscord |
<luatic> "Attempt to index a nil value" |
| 18:08 |
MTDiscord |
<Benrob0329> Not always |
| 18:09 |
MTDiscord |
<luatic> "Attempt to do arithmetics on a table value" |
| 18:09 |
MTDiscord |
<luatic> etc. |
| 18:09 |
MTDiscord |
<luatic> Not always, granted |
| 18:09 |
MTDiscord |
<luatic> But off the top of my head I have to struggle to find an example of MT telling you another type in, say, an error message. |
| 18:09 |
MTDiscord |
<Benrob0329> Yes, they will see them, and we should help give them context, but users will also see class types in the actual code |
| 18:09 |
MTDiscord |
<Benrob0329> errors are only part of the situation |
| 18:09 |
MTDiscord |
<luatic> I guess you consider type names as variable / table names important? |
| 18:10 |
MTDiscord |
<Benrob0329> Yes |
| 18:10 |
MTDiscord |
<luatic> Stuff like VoxelArea etc? |
| 18:10 |
MTDiscord |
<luatic> Agreed, that must be mentioned too. |
| 18:11 |
MTDiscord |
<Benrob0329> Working with the engine means existing code, namespaces, API functions, errors, mentions of things in the UI, etc |
| 18:12 |
MTDiscord |
<Benrob0329> It's all "working with the engine" and it's all important |
| 18:12 |
MTDiscord |
<Benrob0329> We should try to give context to as much of it as pertains to any given thing we're documenting |
| 18:13 |
MTDiscord |
<Benrob0329> An easy way to do that is to use names that they'll see. |
| 18:14 |
MTDiscord |
<Benrob0329> If we call a table with x, y, and z values a vector, they'll likely recognise it as being related to that vector.multiply function they saw someone use |
| 18:14 |
MTDiscord |
<Benrob0329> They don't always need to follow a hyperlink trail to get the info "around the corner", but if it's there that's also helpful |
| 19:00 |
|
appguru joined #minetest-docs |
| 20:18 |
|
appguru joined #minetest-docs |
| 21:11 |
MTDiscord |
<exe_virus> [laptop enabled] Okay, so here's my more informed opinion, though the idea hasn't changed. Let's use vector, integer, and "item_definition" for my example. All three are specialized things for Minetest. Integer is just a special way to use number, item definition is just a standardized lua table, and vector is a specialized meta-table object. All three will be seen multiple times throughout the lua API, and the engine API for |
| 21:11 |
MTDiscord |
that matter, and therefore benefit from having a single source definition for what they are. I.e. avoid duplicate prose. Second, we want only single types for returns or params, that makes logical sense. Third, just because item definition is not a meta table object, doesn't mean it won't be in the future, so might as well give it the full vector treatment. Same for integers, maybe we'll move to 5.4 Lua or 5.1 will get integers or similar. |
| 21:11 |
MTDiscord |
So I propose NOT using the plain lua types as our listed return and param values, and instead give specialized names for things that Minetest has defined, in every case, and remain consistent. That does NOT harm machine readability, as it is merely one table lookup away from what item_defininition is (a table). |
| 21:43 |
MTDiscord |
<GreenXenith> I have no preference about this other than I only want one term per arg/return value. |
| 21:44 |
MTDiscord |
<GreenXenith> Most of the issue I am concerned about is specifying things like "integer vectors" |
| 21:58 |
MTDiscord |
<luatic> Perhaps we should define "node position" as "integer vector in a certain range" somewhere. |
| 21:59 |
MTDiscord |
<GreenXenith> For things like node positions it can definitely be described in prose once and left alone |
| 21:59 |
MTDiscord |
<GreenXenith> especially since Minetest isnt going to freak out if you dont use integers |
| 22:00 |
MTDiscord |
<GreenXenith> The api reference doesnt even cover it in the first place |
| 22:02 |
MTDiscord |
<luatic> Depends. VoxelArea & VoxelManip do freak out unfortunately :[ |
| 22:02 |
MTDiscord |
<luatic> As does hash_node_position |
| 22:02 |
MTDiscord |
<GreenXenith> then describe that in prose when necessary |
| 22:02 |
MTDiscord |
<GreenXenith> strict integer vectors are not used often |
| 22:03 |
MTDiscord |
<GreenXenith> Josiah suggested a notation for subtype, type<sub> may be ok but its not that nice |
| 22:04 |
MTDiscord |
<GreenXenith> number<i> or vector<i> sort of thing |
| 22:04 |
MTDiscord |
<GreenXenith> but I would only want it used when specifics are required |
| 22:04 |
MTDiscord |
<GreenXenith> but at that point separate types for simples and prose for complex types suffices |
| 22:06 |
MTDiscord |
<GreenXenith> When I say "prose" I do mean in the table btw, so its clear whats what |
| 22:16 |
MTDiscord |
<Benrob0329> ^ |
| 22:16 |
MTDiscord |
<GreenXenith> > I have no preference about this other than I only want one term per arg/return value. |
| 22:16 |
MTDiscord |
<GreenXenith> Your question aligns with that, so sure |
| 22:34 |
MTDiscord |
<exe_virus> Yep |
| 22:35 |
MTDiscord |
<exe_virus> And in the documentation, they should be the same |
