Small documentation improvement requests

[curiosity]

https://wiki.factorio.com/Types/LightDefinition#type - the dependent property listing is inconsistent with other pages, where they are listed on the same level as the independent ones.

[Pi-C]

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

Fields

filter
:: string

The condition to filter on. One of "type"

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

-> This is actually just a bit of unfortunate formatting. That filter only supports "type", and is the only one to do so. I added a period at the end of those sentences for the next release though, to make it clearer that there's nothing missing. Thanks for bringing it up!

[curiosity]

https://wiki.factorio.com/Types/SpriteFlags is in dire need of descriptions.

[curiosity]

The wiki doesn't say the maximum number of prototypes for most prototypes so far as I can see.
-> It's listed on all prototypes where it matters (maximum number is 255 or less).

[repne-scasb]

Bug: The new API docs lack enum value lists: viewtopic.php?f=7&t=101185
-> This was fixed.

[curiosity]

https://lua-api.factorio.com/latest/LuaSurface.html#LuaSurface.darkness doesn't say what the possible values interval is.

-> Thanks, added for the next release. It's [0, 1].

[jan1i3]

The description for `scroll_mode` for LuaGuiElement::scroll_to_item mentions "scroll-pane", contrary to the function's (correct) description saying "listbox".

The description for `scroll_mode` for `scroll_to_element` seems to be identical, it is correct in that case, just make sure to not break that one if they are shared.

-> Thanks Jan. If I were pedantic, it could be interpreted as 'in the scroll-pane of the list-box', but you're right that it's confusing, so I changed it for the next release. No worries about them being shared, documentation like this is almost always just copy-pasted, not actually shared. Which is probably where the mistake came from in the first place!

[curiosity]

Oh, all the "can only be used if" remarks are missing. This is a big degradation compared to the old docs.
Speaking of which:

The description for `scroll_mode` for LuaGuiElement::scroll_to_item mentions "scroll-pane", contrary to the function's (correct) description saying "listbox".

This says (or, rather, would have said) "Can only be used if this is scroll-pane". So which is it, scroll pane in general or specifically listbox?

-> Not sure if it didn't show when you made this comment, but the 'Can only be used if this is X' lines are present in the most recent version of the docs website. In that specific case, it only work for listboxes. 'scroll_to_element' can be used for scroll-panes.

[Pi-C]

Class LuaEquipment

Code: Select all

An item in a LuaEquipmentGrid, for example one's power armor.

The role of the power armor is not really clear in this example: Is the armor the item that can be placed in the equipment grid, or is the armor the grid where other things can be placed in? I'd put it this way:

Code: Select all

An item in a LuaEquipmentGrid, for example a fusion reactor placed in one's power armor.

-> Good spot, that is indeed confusing. Appreciate the alternate wording, fixed for the next release.

[Honktown]

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

Fields

filter
:: string

The condition to filter on. One of "type"

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. 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

-> This is true, see response in the next comment.

[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.

[Honktown]

https://lua-api.factorio.com/1.1.53/Con ... otypeData

SelectedPrototypeData could use some details

table SelectedPrototypeData
Fields
base_type
:: string
E.g. "entity".
derived_type
:: string
E.g. "tree".
name
:: string
E.g. "tree-05".

I have to guess and check at the moment.

[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.