Factorio Forums

Heya,

Currently, everything wants a position, whether it's an actual Position or a ChunkPosition. It would be nice if parameters that wanted a ChunkPosition would be renamed to indicate that they want a ChunkPosition. In the overview of classes (https://lua-api.factorio.com/latest/Classes.html) and the overview of the class itself (https://lua-api.factorio.com/latest/LuaSurface.html) it's impossible to tell what type of position functions want. You have to go down to the function-level documentation (https://lua-api.factorio.com/latest/Lua ... _generated) to find if you need to provide a Position or a ChunkPosition. Therefore, it would be nice if the position parameter were renamed to something like chunk when a function wants a ChunkPosition. The suggestion of chunk is made since regenerate_entity takes chunks, though on a personal level I would find chunk_position a little more clear.

Examples:

is_chunk_generated(position)
Parameters
position :: ChunkPosition: The chunk's position.

request_to_generate_chunks(position, radius)
Parameters
position :: Position: Where to generate the new chunks.

regenerate_entity(entities, chunks)
Parameters
chunks :: array of ChunkPosition

Thanks.

While it sounds like an OK idea at first it would mean every single mod that uses those APIs would be broken after making the change when really you should always be looking at the function level documentation and not the overview-level documentation.

How does a doc change break mods? Obviously table keys should not be renamed, but simple function arguments can be "renamed" in the docs without breaking a single thing.

Bilka wrote: ↑

Fri Jan 18, 2019 1:31 am

How does a doc change break mods? Obviously table keys should not be renamed, but simple function arguments can be "renamed" in the docs without breaking a single thing.

Most of the linked places are arguments in tables which can't be renamed without breaking mods.

Renaming the others will just make the docs inconsistent: one is called position and one chunk_position, but the fact it's not called 'chunk_position' here doesn't mean it's a normal position.

The variable name should have no relation to the data type - that's why we provide the data type. Giving a false sense of security by having *some* be related but some not is just making the entire thing worse.

Additionally Hungarian notation can go die.