Small documentation improvement requests

Place to ask discuss and request the modding support of Factorio. Don't request mods here.
curiosity
Fast Inserter
Fast Inserter
Posts: 176
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by 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
Smart Inserter
Smart Inserter
Posts: 1276
Joined: Sun Oct 14, 2018 8:13 am
Contact:

Re: Small documentation improvement requests

Post by 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!
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

curiosity
Fast Inserter
Fast Inserter
Posts: 176
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by curiosity »

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

curiosity
Fast Inserter
Fast Inserter
Posts: 176
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by 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
Burner Inserter
Burner Inserter
Posts: 8
Joined: Sun Jan 09, 2022 1:18 pm
Contact:

Re: Small documentation improvement requests

Post by repne-scasb »

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

curiosity
Fast Inserter
Fast Inserter
Posts: 176
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by 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].

User avatar
jan1i3
Long Handed Inserter
Long Handed Inserter
Posts: 56
Joined: Sun Dec 09, 2018 1:36 pm
Contact:

Re: Small documentation improvement requests

Post by 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!
Also known as JanSharp. jan1i3 was/is my old name ;)

curiosity
Fast Inserter
Fast Inserter
Posts: 176
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by 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:
jan1i3 wrote:
Mon Jan 10, 2022 4:44 pm
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
Smart Inserter
Smart Inserter
Posts: 1276
Joined: Sun Oct 14, 2018 8:13 am
Contact:

Re: Small documentation improvement requests

Post by 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.
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

Honktown
Filter Inserter
Filter Inserter
Posts: 889
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by Honktown »

Pi-C wrote:
Thu Jan 06, 2022 7:16 pm
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.
I have mods! I guess!
Link

Pi-C
Smart Inserter
Smart Inserter
Posts: 1276
Joined: Sun Oct 14, 2018 8:13 am
Contact:

Re: Small documentation improvement requests

Post by Pi-C »

Honktown wrote:
Thu Jan 13, 2022 2:07 pm
Pi-C wrote:
Thu Jan 06, 2022 7:16 pm
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.
A good mod deserves a good changelog. Here's a tutorial (WIP) about Factorio's way too strict changelog syntax!

User avatar
JohnTheCF
Burner Inserter
Burner Inserter
Posts: 19
Joined: Thu Jun 22, 2017 7:15 pm
Contact:

Re: Small documentation improvement requests

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

User avatar
jan1i3
Long Handed Inserter
Long Handed Inserter
Posts: 56
Joined: Sun Dec 09, 2018 1:36 pm
Contact:

Re: Small documentation improvement requests

Post by 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 :D
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.
Also known as JanSharp. jan1i3 was/is my old name ;)

Honktown
Filter Inserter
Filter Inserter
Posts: 889
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by Honktown »

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

-> Added, together with the other changes from 1.1.51.
I have mods! I guess!
Link

Xorimuth
Filter Inserter
Filter Inserter
Posts: 430
Joined: Sat Mar 02, 2019 9:39 pm
Contact:

Re: Small documentation improvement requests

Post by 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
Filter Inserter
Filter Inserter
Posts: 889
Joined: Thu Oct 03, 2019 7:10 am
Contact:

Re: Small documentation improvement requests

Post by 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.
I have mods! I guess!
Link

User avatar
Therenas
Factorio Staff
Factorio Staff
Posts: 213
Joined: Tue Dec 11, 2018 2:10 pm
Contact:

Re: Small documentation improvement requests

Post by 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
Fast Inserter
Fast Inserter
Posts: 176
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

Post by 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.
Therenas wrote:
Sun Jan 23, 2022 10:36 am
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
Burner Inserter
Burner Inserter
Posts: 14
Joined: Mon Sep 13, 2021 6:53 pm
Contact:

Re: Small documentation improvement requests

Post by 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
Fast Inserter
Fast Inserter
Posts: 176
Joined: Wed Sep 11, 2019 4:13 pm
Contact:

Re: Small documentation improvement requests

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

Post Reply

Return to “Modding interface requests”