proofreading 20.7.0 docs

[kurtbrose]

If either was not present, it would raise class:~glom.MatchError. class:object however is matched with func:isinstance(). Since it is not an value-match comparison, it is not required.

[kurtbrose]

(will just make a list here as I run across and then can circle back and fix later)

[kurtbrose]

this is a bit tricky -- I think the behavior of dict is a little under-specified currently

each key in the target dict is matched against each key in the spec dict; the FIRST match stops execution and then the value is matched against the value

so, for example

glom({1:2, 3:4}, Match({int: int, Required(object): object}))

will fail because evaluation never gets to the object part; if you look REALLY closely the comment about the order of evaluation implies a match-one rather than match-every behavior, but it might be worth calling out

[kurtbrose]

oh yea, \ takes precedence over + when formatting the tree; something we can think about if we want it to go the other way

[kurtbrose]

would be nice if this was smart enough to combine the errors kind of like how it will at the bottom

[kurtbrose]

not sure if the verbiage about "initially data was limited" is needed -- I think all the new exception stuff + branches is coming out at the same time

[kurtbrose]

Line 18: We see an “X” indicating our first exception, causing the failure of this branch.

minor thing, X means the end of a branch, not an exception necessarily

[kurtbrose]

would be good if A and Assign docs referred to each other

[kurtbrose]

dang we really need to explain more how scope works -- from this it could be just a global dictionary

we need to explain about how nesting works, children can see parents but not update

[kurtbrose]

but Fill mode isn't documented... whoopsie

I guess that was a known gap

[kurtbrose]

glom’s Match specifier type enables a new mode of glom usage:
 pattern matching. In particular, this mode has been
 designed for nested data validation.

we use the word "mode" twice there, but it doesn't link anywhere or explain further

[kurtbrose]

from context, someone reading might think we are using the plain english meaning of the word rather than introducing them to a new fundamental glom concept

[mahmoud]

not sure if the verbiage about "initially data was limited" is needed -- I think all the new exception stuff + branches is coming out at the same time

Well, I mostly mean that before 20.7.0 Coalesce and Check and such tried to do their own branching-type error descriptions internally, you know? Not referring to the gap between new error discipline to branching, referring to the period from glom launch to branching.

we use the word "mode" twice there, but it doesn't link anywhere or explain further

I was using "mode" colloquially, actually, not trying to introduce the term. Could say "way" instead?

dang we really need to explain more how scope works -- from this it could be just a global dictionary

we need to explain about how nesting works, children can see parents but not update

There's a bit more docs in the "Writing a custom Specifier Type", but not much about read vs write. We probably want to tutorialize it with a coherent example.

if you look REALLY closely the comment about the order of evaluation implies a match-one rather than match-every behavior, but it might be worth calling out

I think match one is a very intuitive assumption, not sure when one would expect match-every.

[kurtbrose]

that makes sense about the branching stuff; at this point I wonder what the balance is on documenting for existing users vs newbiews