Updated pattern match documents

[Brian Goetz]

> Seems that the new document steps away from dedicated matching 
> operator like __matches which we saw before and reuses instanceof 
> instead.

Yes -- the __matches notation was always a placeholder for something, 
which might have been `instanceof` all along; we just weren't sure 
whether `instanceof` could be cleanly extended.  But, given that it can, 
this seems a pretty sensible path.

> Does this mean that sole type name like String which is used in 
> instanceof currently is also a pattern?

This is possible, but we don't go quite that far in the current round; 
instead, we say that instanceof can take a type or a pattern on the 
RHS.  (Related question, in the other direction: can a deconstruction 
pattern take a binding variable for the whole thing, as in `D(int x) d`?)

> This could conflict with named constant. E. g.:
>
> class Test {
>   static final int String = 5;
>
>   void test(Object obj) {
>     if(obj instanceof String) {
>       // obj == 5 or is a string?
>     }
>   }
> }
>

We'd have this problem even more broadly if `T` were a pattern; is

     case String:

a type pattern, or a constant pattern?  At least now, we only have to 
deal with this ambiguity in `instanceof`.  And, it might not be 
unreasonable to restrict the set of patterns you can put on the RHS of 
an `instanceof`; constant patterns on the RHS of instanceof would only 
be there "for completeness".  So we could restrict the grammar to be:

     <id> instanceof ( <type> | <type pattern> | <deconstruction pattern> )

and this problem goes away.  (Saying `x instanceof 3` is kind of silly; 
you could just say `x == 3`.  Same for `var` and `_` patterns.)  And the 
result is that all these patterns are type-based, which is clearly in 
the mission of `instanceof`.

If not, we have a problem where the grammar might simply accept an 
identifier, and then type checking will have to do more work before we 
know what the construct means.  (This happens too with things like 
`a.b.c`; any of those dots could be about field access, or package 
membership, or nested membership; we parse it now and sort it out later, 
according to some set of rules.)