Conditionally Optional

[PennyJim]

I've seen people get tripped up and miss the "mandatory when X" notes a little too often for my liking.

I was thinking we could add a field to the json docs for "optional_conditions" that would handle the append to the description and change it to be listed as Conditionally Optional instead of the very slightly misleading lone Optional.

I was thinking it'd just be an string array of masked links to other fields. There's the problem of how to do 'and' and 'or', but my first stab is to do it the Train Schedule way where top level is always 'or', and second level is 'and'. I've got no attachment to that method, so if you've got something more elegant use that.

Okay just before I'm posting it, I'm now thinking of something similar to how we do filters. That makes a little more sense to me and would allow us to expand the complexity of the 'links' in the future if we need to.

[HEROgoldmw]

I was one of the people running into this. It's really annoying if you read the short description and see the flag optional next to the key. You launch the game with the mod, and suddenly its required.

Clicking on the key, does reveal that its mandatory if another key is not set.

For reference:
https://lua-api.factorio.com/latest/pro ... otype.html

lets say Icon is mandatory if icons isn't set. Both icon and icons are marked as optional. So when quickly viewing the docs for the Shortcut, it said everything except action is optional. But in fact, you need either icon or icons to be preset. Marking those as conditionally optional at least gives the impression and curiosity to look into it before hitting your head against the wall and asking on the mod-dev discord.

[Therenas]

Thanks for the well thought-out suggestions. This idea was actually already tried internally, with a whole system for marking when a certain property is mandatory or optional. It turns out there are a lot of different ways properties can depend on each other, more than the system we had could model, and so the feature was scrapped for now.

The follow-up, simpler idea we had was to allow properties to be 'conditional' in addition to optional or non-optional. That way, it'd be easy to see that there is more to a property, which would then be explained in the description. It's not as neat as a system that models the dependencies, but it does significantly help the reader I think. It's one of the things we'll implement for the next revision of the API docs format.