Time Nick Message 03:27 MTDiscord Yep, links make life good 17:24 MTDiscord @Minetest Docs Team I need a consensus on prose vs tables for internal type details like integer/decimal and bound ranges. 17:25 MTDiscord Integer is used so frequently that I'm against prose. 17:25 MTDiscord As long as the "thing" we're talking about is a link to it's description, I'm good. 17:26 MTDiscord I.e. integers link to the description of what an integer is 17:26 MTDiscord Exactly, that's the best solution. Same as for numbers etc. 17:27 MTDiscord Even better if we can make it a hoverable pop-up thing for the web-based render 17:28 MTDiscord I am in favor of tables or a listing like in object_properties. 17:28 MTDiscord But yeah, beyond that tables always render better than prose 17:28 MTDiscord Links to further documentation are a definite yay. 17:28 MTDiscord We should just have a document with the types. That would also supersede my "terminology" PR. 17:29 MTDiscord 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 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 Yep, I am. 17:33 MTDiscord Alright 17:35 MTDiscord 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 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 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 I listed it as a separate type in object_properties which is what I prefer. 17:39 MTDiscord 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 If it matters then a table will make that importance more obvious. 17:41 MTDiscord 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 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 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 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 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 Well, users won't see "object properties" or "particle definition" as it's own type either 17:43 MTDiscord Yet we would document it as such 17:44 MTDiscord These are purely conceptually typedefs, as in fact Lua pretty much uses ducktyping 17:44 MTDiscord Would we? I'd write that as type "table" and say what it is in the description. 17:44 MTDiscord Dangit we need a document on types as I said 17:44 MTDiscord Because it is a properties table, not an object of it's own. 17:44 MTDiscord So is a vector (except it has a metatable too) 17:45 MTDiscord "actual" objects are different, because they have further functionality than a normal table 17:45 MTDiscord You don't instance a properties table, you just put values in it 17:45 MTDiscord Logically, these "properties" are kinda "data structs", and thus their own type 17:45 MTDiscord It's not an object 17:45 MTDiscord Vectors can be used the same way 17:45 MTDiscord They shouldn't be 17:46 MTDiscord They used to be, but that's not current 17:46 MTDiscord Yet you would say minetest.get_node takes a vector, simply because vectors have been conceptually established as a "type" 17:46 MTDiscord It also makes docs much nicer to write 17:46 MTDiscord We should just save the IRC log and upload it as the advanced usage docs. 17:46 MTDiscord If properties tables are a type, then is every table argument it's own type? 17:47 MTDiscord Legitimate question 17:47 MTDiscord In principle yes 17:47 MTDiscord But the main purpose of defining types is deduplication 17:48 MTDiscord Because node tables have a standard form, property tables each have a standard form, schematic tables have a standard form, etc 17:48 MTDiscord Yeah. I'd definitely "define" ducktypes for those. 17:49 MTDiscord But then, users are likely to actually encounter the terms "node", "schematic", and "properties". "integer" not so much 17:49 MTDiscord Mapnode: Table with fields name, param, param2. Node Definition: Table with lots and lots of fields. 17:49 MTDiscord 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 Why draw a line? All of these are ducktypes. 17:49 MTDiscord Can we have a notation like "type: table (NodeDef[url])" 17:50 MTDiscord 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 It's why the details field it there 17:51 MTDiscord But we also have psudotypes like param2 17:51 MTDiscord "Whole number or not" is considered a type by many languages. 17:52 MTDiscord But not Lua 17:52 MTDiscord Not 5.1, anyways 17:52 MTDiscord You stole my nitpick 17:52 MTDiscord ninja'ed :P 17:52 MTDiscord param2 is a psudotype, but is also easily stated in the description 17:53 MTDiscord 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 But if it's always the technical type, then that's unhelpful in some cases 17:54 MTDiscord "userdata" doesn't mean anything on it's own, for example 17:54 MTDiscord But knowing something is "userdata" is helpful 17:56 MTDiscord 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 we need to start working on an agreed upon baseline 17:57 MTDiscord I don't think anybody will agree with that as you phrased it. 17:58 MTDiscord I would agree that modders should be informed of engine behavior when not knowing it could cause problems for them. 17:58 MTDiscord And only in those cases. 17:59 MTDiscord I..what? 17:59 MTDiscord I don't understand what I'm supposed to glean from that 17:59 MTDiscord The data types the Lua API uses are of course only the basic Lua ones - boolean, number, string, table, userdata, function 18:00 MTDiscord (and nil OFC) 18:00 MTDiscord There's little to add to boolean 18:00 MTDiscord Numbers might integers. It must be made clear that by this we just mean an integer Lua number. 18:01 MTDiscord 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 *dictionary :troll: 18:03 MTDiscord This does not mean only use type(x), take it at face value please 18:04 MTDiscord The definition of table/number/string-based types would mention the internal Lua types. 18:04 MTDiscord +userdata 18:04 MTDiscord So we'd have: Integer: A Lua number with a remainder of zero. 18:05 MTDiscord Node: A table with fields ... 18:06 MTDiscord 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 It should use them, but where? 18:06 MTDiscord I'm arguing that it might be "around the corner" through a "type definition" 18:07 MTDiscord The tables used by the myriads of node functions are actually a decent example 18:07 MTDiscord I'm not talking about just using the term "table" 18:07 MTDiscord Again, take it at face value. 18:07 MTDiscord Would you want to read & write "table (MapNode)" 18:08 MTDiscord 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 I'm not talking about internal types specifically 18:08 MTDiscord But internal types are what the user is going to see 18:08 MTDiscord "Attempt to index a nil value" 18:08 MTDiscord Not always 18:09 MTDiscord "Attempt to do arithmetics on a table value" 18:09 MTDiscord etc. 18:09 MTDiscord Not always, granted 18:09 MTDiscord 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 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 errors are only part of the situation 18:09 MTDiscord I guess you consider type names as variable / table names important? 18:10 MTDiscord Yes 18:10 MTDiscord Stuff like VoxelArea etc? 18:10 MTDiscord Agreed, that must be mentioned too. 18:11 MTDiscord Working with the engine means existing code, namespaces, API functions, errors, mentions of things in the UI, etc 18:12 MTDiscord It's all "working with the engine" and it's all important 18:12 MTDiscord We should try to give context to as much of it as pertains to any given thing we're documenting 18:13 MTDiscord An easy way to do that is to use names that they'll see. 18:14 MTDiscord 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 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 21:11 MTDiscord [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 I have no preference about this other than I only want one term per arg/return value. 21:44 MTDiscord Most of the issue I am concerned about is specifying things like "integer vectors" 21:58 MTDiscord Perhaps we should define "node position" as "integer vector in a certain range" somewhere. 21:59 MTDiscord For things like node positions it can definitely be described in prose once and left alone 21:59 MTDiscord especially since Minetest isnt going to freak out if you dont use integers 22:00 MTDiscord The api reference doesnt even cover it in the first place 22:02 MTDiscord Depends. VoxelArea & VoxelManip do freak out unfortunately :[ 22:02 MTDiscord As does hash_node_position 22:02 MTDiscord then describe that in prose when necessary 22:02 MTDiscord strict integer vectors are not used often 22:03 MTDiscord Josiah suggested a notation for subtype, type may be ok but its not that nice 22:04 MTDiscord number or vector sort of thing 22:04 MTDiscord but I would only want it used when specifics are required 22:04 MTDiscord but at that point separate types for simples and prose for complex types suffices 22:06 MTDiscord When I say "prose" I do mean in the table btw, so its clear whats what 22:16 MTDiscord ^ 22:16 MTDiscord > I have no preference about this other than I only want one term per arg/return value. 22:16 MTDiscord Your question aligns with that, so sure 22:34 MTDiscord Yep 22:35 MTDiscord And in the documentation, they should be the same