Split read/write types for `@field`s

[justarandomgeek]

In Factorio's API (and presumably many others?) we have a large number of API objects with properties that accept assignment from a wide union of types but only ever return one specific member of that union when read. In particular, there are many that accept writing nil to reset them to default states, but will never read as nil.

Unfortunately, since we can only give the @field a single type, we currently have to give it the wider of the two, which results in many spurious warnings about nil checks and type tests on values read from these affected properties.

Would it be possible to have separate types for @fields to validate against for read/write access?

[justarandomgeek]

aside: this would also improve support for both read-only and write-only fields (which we have a few of each of) by simply specifying the other side as never!

[xuhuanzy]

Perhaps we need to add a new annotation tag for support, but not right now.

[PennyJim]

My idea for the tag annotation is to have it be described like this:

---@class example
---
---@field (read) readwrite_field_one A
---@field (write) readwrite_field_one A|B|C
---
---@field (split) readwrite_field_two A, A|B|C -- I wouldn't be heartbroken to lose this syntax
---
---@field (read) readonly_field A   -- Implicitly sets the unset `readonly_field` write to `never`
---@field (write) writeonly_field B -- Implicitly sets the unset `writeonly_field` read to `never`

I see that @readonly does exist for variables, but I see no way to get it to work for class fields where I think it makes a similar amount of sense, if not more, but it being a @ tag feels uncomfortable within a class definition.