Some non-/conditionally-required properties not marked optional

[aebonyne]

In writing my ReflectionLibrary mod, I found a few instances of data.raw not satisfying my interpretation of the documentation. My mod has a list of workarounds that modify the in-memory docs such that data.raw passes my checks. I would entirely believe that my checks are wrong, not the docs, but here's what I found.

Note that since nearly all of these are conditionally optional, I added two annotation kinds that I used in my workarounds:

• "rest_optional_if" to capture the pattern used by RotatedAnimation.layers and a few other places where if that property is set, it's a list of values to read and the other properties are ignored. "rest_optional_if" is set on the type and is the same of that property.
• "optional_if" to handle at least one alternative needing to be set. It's a list of property names and if any of those properties are true (i.e. not false or nil due to TileTransitionsVariants's handling of "empty_transitions") then it acts like "optional" was set to true.

1. SpotNoiseArguments.comment is not marked optional; I assume it's supposed to be optional.
2. "steam-all-the-way" has "excluded" but not "included" despite DontUseEntityInEnergyProductionAchievementPrototype listing both as required.
3. "rest_optional_if" is used for FootstepTriggerEffectItem.actions, and RotatedAnimation/RotatedSprite.layers
4. RecipeData.results is "optional_if" "result" is set, which is stated by the description, but not in a machine-readable way.
5. data.raw.turret["small-worm-turret"].spawn_decoration[_] do not have a "type" property despite spawn_decoration saying the type is Array[CreateDecorativesTriggerEffectItem] where "type" is not marked optional. (I'm guessing "type" might always be optional if it's not needed to determine the type?)
6. In data.raw["noise-expression"]["0_17-lakes-elevation"].expression.arguments[3].arguments[1].arguments[1].arguments[1].arguments[1].arguments[1].arguments.points, points is defined to be a NoiseArrayConstruction but it's actually a NoiseVariable.
7. ItemProductPrototype/FluidProductPrototype both say in the description that the non-optional fields `amount_min` and `amount_max` are loaded only if `amount` is not defined, but don't say that in a machine-readable way. I added "optional_if" = { "amount" }.
8. Similarly, TileTransitionsVariants has multiple fields with descriptions like "This or side_mask needs to be specified if empty_transitions is not true." which is not given in a machine-readable way. I added "optional_if" = { "empty_transitions", "side_mask" }.
9. I'm not sure this one is actually a documentation bug or a bug in my understanding the semantics: BoundingBox is declared as a tuple but sometimes given as a struct with the keys "left_top" and "right_bottom". But I vaguely recall something about tuples and structs sometimes being interchangeable from Factorio's point of view.

(There's also no machine-readable way to get information on CraftingMachinePrototype.fluid_boxes.off_when_no_fluid_recipe, but that's also the only place that I know of where there's an extra field on an array, which would require a whole separate way to describe it in the JSON.)

[Bilka]

Thank you finding these issues and listing them here, much appreciated.

1 + 2: Yes, docs changed for the next doc release.
3: I cannot change anything about FootstepTriggerEffectItem without introducing a way to mark inherited properties as not loaded (tiles is mandatory even when actions is given). RotatedAnimation and RotatedSprite got their mandatory properties marked as "Only loaded, and mandatory if" with the $optional tags.
4: A bunch of things were not marked correctly with result and results, fixed.
6: Yeah, a variable for an array - fixed.
7 + 8: Added $optional tags.
9: In some parts of the prototype loading the game simply uses the equivalent of pairs to iterate arrays. In others it requires arrays to actually be array-like. This is getting moved towards requiring array-likes (numeric indices without gaps) in 2.0. In the case of BoundingBox, the keys are ignored and can be anything, because the game uses the pairs equivalent.

The problem with crafting machine fluid boxes is known and the only spot where basic type information like this is unavailable, due to the issue you give.

Not addressed from your post yet because these are large tasks: Machine readable conditionally mandatory and conditionally loaded and all the variations that made us not implement it from the get go. Your point 5.