Documentation missing around +:: and +::: usage

[jamiechapmanbrn]

We've just started using jsonnet at my organization, and seeing some open source projects are using +:: almost exclusively for creating and adding to hidden fields, but it isn't clear what it does without understanding language specification or discovering by trial-and-error.

[sparkprime]

I agree with this. The tutorial says:

Hidden fields, defined with ::, which do not appear in generated JSON
The +: field syntax for overriding deeply nested fields

But there isn't an example of :: after that, it appears in the 2nd example below.

Also, although these features are orthogonal it's not explicit about what the 6 combinations mean together. There is no occurrence of ::: +:: or +::: in the tutorial at all.

[sparkprime]

In case anyone wants to know what the difference is:

• : means "inherit visibility from corresponding field in the parent, or visible if there was none"
• :: means "invisible, always"
• ::: means "visible, always"

Putting the + on the front is orthogonal -- you will be extending from super whenever there is a + and the visibility of the field is decided by the number of colons and the visibility of the corresponding parent field.

The most common to use by far is : :: and +:. Note that +:: is unnecessary if the parent field is already hidden (use +: instead). Use of ::: and +::: is very rare but sometimes necessary.

[abentley]

It might be helpful if the tutorial documented + as an optional prefix. Right now, it seems to say that +: is an atomic unit, rather than a prefixed version of :.