nailed "our" declarations, and better warnings on duplicate

"our" declarations

p4raw-id: //depot/perl@4801

1 files changed, 28 insertions, 0 deletions

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 4e38db25ca..d730b43e47 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -2788,6 +2788,34 @@ declared global variable without qualifying it with a package name.
 (But only within the lexical scope of the C<our> declaration.  In this
 it differs from "use vars", which is package scoped.)
 
+An C<our> declaration declares a global variable that will be visible
+across its entire lexical scope, even across package boundaries.  The
+package in which the variable is entered is determined at the point
+of the declaration, not at the point of use.  This means the following
+behavior holds:
+
+    package Foo;
+    our $bar;		# declares $Foo::bar for rest of lexical scope
+    $bar = 20;
+
+    package Bar;
+    print $bar;		# prints 20
+
+Multiple C<our> declarations in the same lexical scope are allowed
+if they are in different packages.  If they happened to be in the same
+package, Perl will emit warnings if you have asked for them.
+
+    use warnings;
+    package Foo;
+    our $bar;		# declares $Foo::bar for rest of lexical scope
+    $bar = 20;
+
+    package Bar;
+    our $bar = 30;	# declares $Bar::bar for rest of lexical scope
+    print $bar;		# prints 30
+
+    our $bar;		# emits warning
+
 =item pack TEMPLATE,LIST
 
 Takes a LIST of values and converts it into a string using the rules