Document the quirks of SUPER, especially the fact that it it

relative to the current package and not to the invoking object.

p4raw-id: //depot/perl@22036

diff --git a/pod/perlboot.pod b/pod/perlboot.pod
index 8eaac86..927777d 100644 (file)
--- a/pod/perlboot.pod
+++ b/pod/perlboot.pod
@@ -382,7 +382,8 @@ listed in C<@ISA>) automatically:
     }
 
 So, C<SUPER::speak> means look in the current package's C<@ISA> for
-C<speak>, invoking the first one found.
+C<speak>, invoking the first one found. Note that it does I<not> look in
+the C<@ISA> of C<$class>.
 
 =head2 Where we're at so far...
 

diff --git a/pod/perlbot.pod b/pod/perlbot.pod
index dc632ea..4507d4f 100644 (file)
--- a/pod/perlbot.pod
+++ b/pod/perlbot.pod
@@ -243,6 +243,9 @@ where that method is defined.
        $foo->goo;
        $foo->google;
 
+Note that C<SUPER> refers to the superclass of the current package
+(C<Foo>), not to the superclass of C<$self>.
+
 
 =head1 USING RELATIONSHIP WITH SDBM
 

diff --git a/pod/perlobj.pod b/pod/perlobj.pod
index 73b67de..16013fc 100644 (file)
--- a/pod/perlobj.pod
+++ b/pod/perlobj.pod
@@ -275,6 +275,16 @@ current class's C<@ISA> list.
         $self->SUPER::display("Name", @args);
     }
 
+It is important to note that C<SUPER> refers to the superclass of the
+I<current package> and not to the superclass of the object. Also, the
+C<SUPER> pseudo-class can only currently be used as a modifier to a method
+name, but not in any of the other ways that class names are normally used,
+eg:
+
+    something->SUPER::method(...);     # OK
+    SUPER::method(...);                        # WRONG
+    SUPER->method(...);                        # WRONG
+
 Instead of a class name or an object reference, you can also use any
 expression that returns either of those on the left side of the arrow.
 So the following statement is valid:

diff --git a/pod/perltoot.pod b/pod/perltoot.pod
index 03372c7..2497063 100644 (file)
--- a/pod/perltoot.pod
+++ b/pod/perltoot.pod
@@ -940,7 +940,8 @@ comes to the rescue here.
 This way it starts looking in my class's @ISA.  This only makes sense
 from I<within> a method call, though.  Don't try to access anything
 in SUPER:: from anywhere else, because it doesn't exist outside
-an overridden method call.
+an overridden method call. Note that C<SUPER> refers to the superclass of
+the current package, I<not> to the superclass of C<$self>.
 
 Things are getting a bit complicated here.  Have we done anything
 we shouldn't?  As before, one way to test whether we're designing