Small documentation improvement requests

[curiosity]

Prototype/Turret#attack_parameters - the description is wrong. The vanilla gun turret exists without ammo_type, so obviously it's not required. You may want to say that specific turret subtypes require some parent fields to be a certain way, though IDK how you would present that.
-> Thanks, fixed.

[Honktown]

Small request:
https://lua-api.factorio.com/1.1.56/Lua ... ergy_usage

Energy usage could be listed as joules/tick or "watts but in ticks"/"tick-watts". There are some other values that could probably have that added: max_energy_usage, max_energy_production, consumption... Probably everything dealing with power and energy if one were being a completionist.

[Xorimuth]

https://lua-api.factorio.com/latest/Lua ... al_spacing

LuaHorizontalFlow should be LuaHorizontalFlowStyle?

Also why can't this be used on a frame


-> It should be, thanks, fixed for the next release. As for your question, that's how it works unfortunately, you can make an interface request if you want a proper answer, otherwise I can recommend adding a flow to the frame that you then set this property on.

[JohnTheCF]

A recent edit (https://wiki.factorio.com/index.php?tit ... did=188205) added a "Can't be negative" note to a field/protperty that has a type of unsigned integer. Because unsigned integers can't be negative, I think that this note is redundant here and just specifying the type is enough.
-> Honktown reverted the edit, thank you. Reverting the edit yourself is usually faster than waiting on me to get to it, so I would recommend doing that instead of posting here (like Honktown did, thank you again).

[Xorimuth]

https://lua-api.factorio.com/latest/Lua ... istic_slot
"spider-vehicules" is spelt wrong and the 's' looks weird.
Should the same caveat be on get_vehicle_logistic_slot?

https://lua-api.factorio.com/latest/Lua ... _activated
typo in description: actived -> activated

-> Yes to all, thank you, fixed for the next release.

[jimmyhunter]

hey hello
i am creating a prototype unit and i am stumbling on this prototype:

https://wiki.factorio.com/Types/BaseAttackParameters

all good and well but now i have defined almost everything except for this:

https://wiki.factorio.com/Types/CyclicSound

what exactly does this refer to?
the begin and end sound might be understandable but i would give more context than it currently has.
i have no clue when the middle sound should be defined as or how i should interpreted it as a sound at all really

in short: explain begin_sound and end_sound and give additional clarification on middle_sound

thank you, sincerely
Jimmy.
-> I added extra descriptions to the sounds in BaseAttackParameters and also in CyclicSounds, I hope it helps

[curiosity]

LuaItemStack.set_stack should say why it can fail.

-> Improved, thanks.

[JohnTheCF]

https://wiki.factorio.com/Types/Sound#variations
variations, max_speed property description says that max_speed is mandatory if max_speed is present. Probably min_speed was meant there.
-> Thank you for finding this, fixed.

[curiosity]

Types/StyleSpecification#effect need description, or at the very least a list of possible values.
-> The list of possible values is hardcoded to one value, severely limiting its usefulness. But it's documented now, thank you for pointing it out.

[JohnTheCF]

https://wiki.factorio.com/Types/RadiusV ... cification
default value for distance is 0, but it also says that it shoukd be grater than 0
-> Should be greater or equal. Thanks for noticing it, I fixed the doc.

[curiosity]

Effects of this module; nil if this is not a module.
Can only be used if this is ModuleItem

So can it or can it not be used on other items?

-> Thanks, I decided to remove the redundant description text.

[Xorimuth]

https://lua-api.factorio.com/latest/Lua ... parameters

This returns nil when the prototype's item_slot_count is set to 0. This should either be specified (at least with a question mark) or changed to return an empty table.

-> Good spot, thanks, fixed for the next release.

[Pi-C]

About LocalisedString:

concept LocalisedString
…
Furthermore, when an API function expects a localised string, it will also accept a regular string (i.e. not a table) which will not be translated, as well as a number or boolean, which will be converted to their textual representation.

I've set [code]LuaGuiElement.tooltip = nil[/code] expecting to see no tooltip at all, but instead, "nil" was displayed. If that is the correct behavior, the explanation should include nil along with "number or boolean":

Furthermore, when an API function expects a localised string, it will also accept a regular string (i.e. not a table) which will not be translated, as well as a number, a boolean or nil, which will be converted to their textual representation.

Otherwise, there should be a note that this applies at least in some cases:

Furthermore, when an API function expects a localised string, it will also accept a regular string (i.e. not a table) which will not be translated, as well as a number or boolean, which will be converted to their textual representation.

Note: In some cases (e.g. for LuaGuiElement.tooltip), nil will also be converted to its textual representation.

-> The localised string parser explicitly converts a nil value to the string "nil", which I've noted in the docs for the next release.

[curiosity]

Gets the entities output inventory if it has one.

entity's

-> Thanks, fixed.

[curiosity]

Can we get a description of what FluidBox#production_type is supposed to mean as opposed to PipeConnectionDefinition#type? Description for both, maybe?

[hackamod]

https://wiki.factorio.com/Tutorial:Loca ... ile_format

There was no mention of comments in the file here.
-- does not work, and I assumed it did, then I waited for a reply in a bug report.
# or ; seems to be the answer for a comment here and might save the next person some time.

-> Thanks for pointing this out, I added the comment characters to the example.

[-DeadlyKitten]

request to add information to https://wiki.factorio.com/Tutorial:Localisation about how to make a multi line description (\n turns into a newline character)
and how to create/change it programmatically (i dont know this but know it is posible)

-> Added the note on \n, programmatic creation (as in, creation with parameters) should already be covered by the page.

[Honktown]

If an empty players table passed to LuaRendering draw functions means "everyone" not "nobody". It'd be convenient if that were noted somewhere.

-> I noted this on all draw methods for both the players and forces parameters.

[curiosity]

If an empty players table passed to LuaRendering draw functions means "everyone" not "nobody". It'd be convenient if that were noted somewhere.

It is, though maybe not where you'd expect: LuaRendering.set_players.

[Honktown]

Clarity on LuaEntity secondary_selection_box is desired:
1) when does this apply?
2) there's no prototype definition for secondary selection box in a Prototype/Entity
3) it's not in the LuaEntityPrototype
4) is it entity-biased like LuaEntity.selection_box, or is it in un-adjusted dimensions?

-> This one only applies to curved rails. Since it's determined automatically, it's not a property of the prototype. I noted this for the next release, thanks.