[foreign] RFR 8218742: Refine Scope API

[Maurizio Cimadamore]

Hi,
this is an official RFR for the changes discussed in the writeup in [1] 
and in the subsequent thread [2].

Webrev:

http://cr.openjdk.java.net/~mcimadamore/panama/8218742/

I've updated the examples document to reflect the API changes, as well 
as polished the code, fixup javadocs etc.

The tests pass on all platforms.

Cheers
Maurizio

[1] - http://cr.openjdk.java.net/~mcimadamore/panama/scopes.html
[2] - 
https://mail.openjdk.java.net/pipermail/panama-dev/2019-January/003926.html