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

1 files changed, 10 insertions, 0 deletions

diff --git a/pod/perlobj.pod b/pod/perlobj.pod
index 73b67dee9a..16013fc903 100644
--- 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: