From 546102f55aa6e75a32262d59bce165ac3298c172 Mon Sep 17 00:00:00 2001
From: JJ Merelo <jjmerelo@gmail.com>
Date: Thu, 31 May 2018 12:23:45 +0200
Subject: [PATCH] Expands confusing name lookup examples

And fixes some of them. Closes #969
---
 doc/Language/packages.pod6 | 34 +++++++++++++++++++++++-----------
 1 file changed, 23 insertions(+), 11 deletions(-)

diff --git a/doc/Language/packages.pod6 b/doc/Language/packages.pod6
index af02e70ed..1a0de1f17 100644
--- a/doc/Language/packages.pod6
+++ b/doc/Language/packages.pod6
@@ -22,28 +22,40 @@ with a longer name to disambiguate.
 A I<name> is anything that is a legal part of a variable name (not counting the
 sigil). This includes:
 
-=for code :skip-test
-$foo                # simple identifiers
-$Foo::Bar::baz      # compound identifiers separated by ::
-$Foo::($bar)::baz   # compound identifiers that perform interpolations
-$42                 # numeric names
-$!                  # certain punctuation variables
+=for code
+class Foo {
+    sub zape () { say "zipi" }
+    class Bar {
+        method baz () { return 'Þor is mighty' }
+        our &zape = { "zipi" };
+        our $quux = 42;
+    }
+}
+
+my $foo;                # simple identifiers
+say Foo::Bar.baz;       # Calling a method; OUTPUT: «Þor is mighty␤»
+say $Foo::Bar::zape;    # compound identifiers separated by ::; OUTPUT: «zipi␤»
+my $bar = 'Bar';
+say $Foo::($bar)::quux; # compound identifiers with interpolations; OUTPUT: «42␤»
+$42;                    # numeric names
+$!;                     # certain punctuation variables
 
 X<|::,package>
 C<::> is used to separate nested package names.
 
 =head2 Package-qualified names
 
-Ordinary package-qualified names look like:
-
-    $Foo::Bar::baz      # the $baz variable in package Foo::Bar
+Ordinary package-qualified names look like; C<$Foo::Bar::quux> would be the
+C<$quux> variable in package C<Foo::Bar>; C<Foo::Bar::zape> would represent the
+C<&zape> variable in the same package.
 
 Sometimes it's clearer to keep the sigil with the variable name, so an
 alternate way to write this is:
 
-    Foo::Bar::<$baz>
+    Foo::Bar::<$quux>
 
-This is resolved at compile time because the variable name is a constant.
+(This does not work with the C<&zape> variable) The name is resolved at compile
+time because the variable name is a constant.
 
 If the name part before C<::> is null, it means the package is unspecified and
 must be searched for. Generally this means that an initial C<::> following the