[perl #36538] perlfunc/our contradicts itself

From: "Michael G Schwern via RT" <perlbug-followup@perl.org>
Message-ID: <rt-3.0.11-36538-117411.7.57026072725992@perl.org>

p4raw-id: //depot/perl@25148

1 files changed, 17 insertions, 11 deletions

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 0235c3ec7f..447dad3fb1 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -3242,15 +3242,21 @@ See L<perlunicode> and L<encoding> for more about Unicode.
 
 =item our TYPE EXPR : ATTRS
 
-An C<our> declares the listed variables to be valid globals within
-the enclosing block, file, or C<eval>.  That is, it has the same
-scoping rules as a "my" declaration, but does not create a local
-variable.  If more than one value is listed, the list must be placed
-in parentheses.  The C<our> declaration has no semantic effect unless
-"use strict vars" is in effect, in which case it lets you use the
-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.)
+C<our> associates a simple name with a package variable in the current
+package for the remander of the lexical scope.  The listed variables
+are declared to be valid globals within the enclosing block, file, or
+C<eval>.  That is, it has the same scoping rules as a "my"
+declaration, but does not create a local variable.  When C<use strict
+'vars'> is in effect, the C<our> declaration lets you use the 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.)
+
+If more than one value is listed, the list must be placed in
+parentheses.
+
+    our $foo;
+    our($bar, $baz);
 
 An C<our> declaration declares a global variable that will be visible
 across its entire lexical scope, even across package boundaries.  The
@@ -3263,10 +3269,10 @@ behavior holds:
     $bar = 20;
 
     package Bar;
-    print $bar;		# prints 20
+    print $bar;		# prints 20 as it refers to $Foo::bar
 
 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
+if they are in different packages.  If they happen to be in the same
 package, Perl will emit warnings if you have asked for them.
 
     use warnings;