Documentation Improvement Requests

[Pi-C]

This looks incomplete -- perhaps somebody removed the rest of the sentence accidentally?

That's the automation of the docs. If you look at the other filters, they have more than one type of filter, so 'one of "a" or "b"' makes sense.

Makes sense, but still: The description looks incomplete, so it's rather confusing than helpful.

Logically the plural-ness could be split into two or three cases... one (first), two (first and last), and "many" (first, last, middles). -> one = "filter of type a", two = "filter of type a[,] or b", many = "filter of type a, [b, c, ...], or last

Agreed! Two cases (singular/plural) are necessary, three cases (1, 2, >2) would be even better.

-> Alright, because you've been so nice about it, I added a separate case for when there's only one option for the next release. Thanks for bringing it up.

[JohnTheCF]

https://wiki.factorio.com/Prototype/AutoplaceControl

you will not able to change it because gui wasn`t display it.

It shouldn't be "wasn't", probably "won't" or "will not"

-> Fixed the edit. Please keep in mind that the wiki can be edited by anyone, so some edits may not have the expected quality until they have been corrected by someone else. You are invited to do these corrections yourself.

[jan1i3]

LuaProfiler says "They can be used anywhere a LocalisedString is used." However there are 3 locations I found where LocalisedStrings are part of property trees causing this to not apply (meaning LuaProfilers are not usable). I'm pretty sure I've gone through and tested all data structures that can contain LocalisedStrings (since not all of them use property trees when parsing).

LuaSurface::create_entity (with "flying-text")
LuaGuiElement::add (lots of LocalisedStrings in here)
LuaEntity.add_market_item (with Offer with TechnologyModifier type "nothing" and effect_description)

Note that you can actually directly assign to the properties that take LocalisedStrings after creating the entity or gui element and it works (though it might not be the most intentional that it does, see link below). I don't think you can directly set the market offer's LocalisedString, so that's the only place where you truly can't use LuaProfilers, but that's also kind of ridiculous
And note that I only tested caption for LuaGuiElements, but I'm confident that the same applies to the others.

reference: viewtopic.php?p=560263#p560263

-> Thanks for the well-researched comment, I noted those three exceptions on LuaProfiler for the next release. I didn't bring up the fact that you could set them after the fact. If you have a good reason for me to mention that, please let me know.

[Honktown]

[code]protected_from_tile_building[/code] is missing from the wiki

-> Added, together with the other changes from 1.1.51.

[Xorimuth]

https://lua-api.factorio.com/latest/Lua ... quest_path should point to CollisionMaskWithFlags, not just CollisionMask. There could be lots of instances of this.

https://lua-api.factorio.com/latest/Con ... kWithFlags should explain the flags or link to the explanations at https://wiki.factorio.com/Types/CollisionMask

-> Thanks for the hints, I did addressed both points for the next release.

[Therenas]

I just wanted to make a quick note on all the Position conversation: I agree that it's all a pretty big mess at the moment. The fundamental issue is that read and write have to have the same type in the docs, even when they don't behave the same, so you end up with confusing concepts that try to encompass both somehow, but make it hard to know what really applies. The solution to this in my mind is to allow differing read and write types on attributes if necessary. This is a somewhat involved solution though, so it'll take some time.
-> The Position concept has been removed for the next version, everything now uses the specialized positions like MapPosition and TilePosition. So this is now fixed by it no longer being confusing what Position is for.

[curiosity]

https://lua-api.factorio.com/latest/LuaTrain.html#LuaTrain.carriages - are these listed in the order they occur in-game, in some other order or in no particular order?

-> I added an explanation for the next release. The front of the train is the one most locomotives are pointing to. If it's a tie, North and West take precedence.

I just wanted to make a quick note on all the Position conversation: I agree that it's all a pretty big mess at the moment. The fundamental issue is that read and write have to have the same type in the docs, even when they don't behave the same, so you end up with confusing concepts that try to encompass both somehow, but make it hard to know what really applies. The solution to this in my mind is to allow differing read and write types on attributes if necessary. This is a somewhat involved solution though, so it'll take some time.

Thank you for not ignoring this, because to me it looked like the issue was fixed in the worst possible way.

[InappropriatePenguin]

LuaEntity :: crafting_progress

In previous versions of the API (like this one), this property had a note that it can only be used for crafting machines. This note is no longer there even though I still believe it applies.

-> As noted before, this has been fixed for the next release.

[curiosity]

It seems like someone goes manually over every method/property and re-adds these notes manually. There's a lot of them missing (but, notably, there are some for the topmost methods) on LuaEntity despite my earlier report being crossed out. There is still a lot missing even on the LuaGuiElement, the very page that was linked when I reported this! WTF? Don't cross out something that wasn't fixed. When I said that all of them are missing, I meant all of them.

edit: ah, I see, it was fixed for methods, but not for properties.

-> You're right, it's being looked into. This has been fixed for the next release.

[curiosity]

https://lua-api.factorio.com/latest/Global.html - doesn't say that LuaObjects can't be stored as keys.

-> Noted for the next release, thanks. Actually, this is not quite right. LuaObjects can be used as keys, it just doesn't really make sense since you won't be able to index them after save/load with the 'same' LuaObject, since it'll be a new table. This is the same principle as using regular tables as keys, so it's not appropriate to note this behavior here.

[curiosity]

https://lua-api.factorio.com/latest/LuaSurface.html#LuaSurface.find_tiles_filtered - area.right_bottom is treated as exclusive by this function (area.left_top is properly inclusive), which is not what you'd expect from something called "bounding box".

Fixed for 1.1.54 - right bottom corner will be included (boskid)

[curiosity]

https://wiki.factorio.com/Prototype/Tile#transitions - says that to_tiles is a string when in fact it's a table (or maybe an array) of strings. And the (lack of) formatting of the additional properties is pretty awful, if I'm honest. All of them in a single line like that looks like a mess.

-> Fixed.

[Pi-C]

Description of LuaForce.character_running_speed_modifier:

character_running_speed_modifier :: double [Read/Write]

Modifies the running speed of all characters in this force by the given value as a percentage. Setting the running modifier to 0.5 makes the character run 50% faster. The minimum value of -1 reduces the movement speed by 100%, resulting in a speed of 0.

Two questions:

• According to the description, this modifies the property for all characters on the force. I assume the same is true for the different character_*_bonus properties. Shouldn't their descriptions also show "Modifies X of all characters in this force"?
• What exactly does "all characters in this force" mean? Is it really all characters, including those that are not connected to a player?

[Wiwiweb]

For EntityPrototypeFilter:

https://lua-api.factorio.com/latest/Con ... typeFilter

It says `type` expects a string but it can actually be a table of strings too.

Screenshot 2022-02-02 080659.png (34.75 KiB) Viewed 4912 times

Probably the same for all the `*PrototypeFilter` classes.

-> Thanks, fixed for the next release.

[curiosity]

https://lua-api.factorio.com/latest/LuaGameScript.html#LuaGameScript.player needs clarification for what counts as "typing at the console". E.g. it exists in command handlers, but not in the on_console_chat or on_console_command handler. Is there anything else that may be considered "typing at the console" and does it exist during that?

-> Thanks, I clarified this for the next release. The only places it is not nil are command handlers and /c-type console commands.

[curiosity]

https://lua-api.factorio.com/latest/LuaSurface.html#LuaSurface.find_entities_filtered leads one to believe (or, at least, doesn't contradict) that the radius option searches center to center. Should explicitly say what kind of check it does.

-> I noted that it searches for the center of entities for the next release.

[Therax]

References to https://lua-api.factorio.com/latest/Con ... l#Position should be removed and replaced with references to MapPosition, TilePosition (which is entirely redundant with Position's current definition), or ChunkPosition as appropriate.

Several APIs and other Concepts that reference Position (such as BoundingBox) are actually MapPosition-based and accept fractional coordinates, which the documented definition of Position disallows.

-> Indeed, this was the solution that we went for. The Position concept has been removed for the next version, everything now uses the specialized positions like MapPosition and TilePosition.

[Silari]

Several APIs and other Concepts that reference Position (such as BoundingBox) are actually MapPosition-based and accept fractional coordinates, which the documented definition of Position disallows.

See Klonan's post on that - viewtopic.php?p=558683#p558683 . Writing rounds values, so even things that only take Position will accept non-integer values to make it easier to pass things directly without needing to try and fix them yourself.

Also see Therenas' post - viewtopic.php?p=560440#p560440 that says he's hoping to fix all the position stuff up but the docs simply aren't setup that way right now.

-> The Position concept has been removed for the next version, everything now uses the specialized positions like MapPosition and TilePosition. So this is now fixed by it no longer being confusing what Position is for.

[curiosity]

See Klonan's post on that - viewtopic.php?p=558683#p558683 . Writing rounds values, so even things that only take Position will accept non-integer values to make it easier to pass things directly without needing to try and fix them yourself.

Also see Therenas' post - viewtopic.php?p=560440#p560440 that says he's hoping to fix all the position stuff up but the docs simply aren't setup that way right now.

Klonan is ultimately missing the point in that post. And beside that, rounding was never an issue either for usability or documentation. It seems like it is supposed to say that TilePosition converts fractional values to integers, which IMO makes it quite clear that you can pass a MapPosition to whatever takes TilePosition. There is absolutely no issue with this, you just have to specify the conversion rules.

Therax is right that there is redundancy right now and, as the most vaguely named, it makes sense for Position to go.

-> Indeed, this is the solution that we went for. The Position concept has been removed for the next version, everything now uses the specialized positions like MapPosition and TilePosition.

[Bilka]

Regarding the whole Position confusion, as suggested a few times here, we decided to get rid of Position and have everything use the more specialized types like MapPosition, TilePosition, ChunkPosition and Vector. I went through the docs and adjusted everything to refer to the correct specialized type, so everything should be documented as the correct type now. This also introduces the new concept EquipmentPosition, which is used by equipment.

This should make it a lot more clear what each position type is used for. The confusion regarding rounding should also be solved with this change. The change will be part of the next release.