position :: Position and position :: ChunkPosition

Things that we aren't going to implement
Post Reply
project6
Inserter
Inserter
Posts: 22
Joined: Sat Aug 15, 2015 10:31 pm
Contact:

position :: Position and position :: ChunkPosition

Post by project6 »

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

Rseding91
Factorio Staff
Factorio Staff
Posts: 13171
Joined: Wed Jun 11, 2014 5:23 am
Contact:

Re: position :: Position and position :: ChunkPosition

Post by Rseding91 »

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.
If you want to get ahold of me I'm almost always on Discord.

Bilka
Factorio Staff
Factorio Staff
Posts: 3123
Joined: Sat Aug 13, 2016 9:20 am
Contact:

Re: position :: Position and position :: ChunkPosition

Post by Bilka »

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.
I'm an admin over at https://wiki.factorio.com. Feel free to contact me if there's anything wrong (or right) with it.

Rseding91
Factorio Staff
Factorio Staff
Posts: 13171
Joined: Wed Jun 11, 2014 5:23 am
Contact:

Re: position :: Position and position :: ChunkPosition

Post by Rseding91 »

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.
If you want to get ahold of me I'm almost always on Discord.

Post Reply

Return to “Won't implement”