Document that POSIX::abs, ::alarm, ::atan2, ::chdir, ::chmod need explicit argument.

Reformat code in one foreach block for readability.  Make podcheck happy.

For: RT #132145

2 files changed, 39 insertions, 15 deletions

diff --git a/ext/POSIX/lib/POSIX.pod b/ext/POSIX/lib/POSIX.pod
index 9d2c0320d6..722cf8ea8c 100644
--- a/ext/POSIX/lib/POSIX.pod
+++ b/ext/POSIX/lib/POSIX.pod
@@ -81,8 +81,13 @@ if the handler does not return normally (it e.g.  does a C<longjmp>).
 
 =item C<abs>
 
-This is identical to Perl's builtin C<abs()> function, returning
-the absolute value of its numerical argument.
+This is identical to Perl's builtin C<abs()> function, returning the absolute
+value of its numerical argument (except that C<POSIX::abs()> must be provided
+an explicit value (rather than relying on an implicit C<$_>):
+
+    $absolute_value = POSIX::abs(42);   # good
+
+    $absolute_value = POSIX::abs();     # throws exception
 
 =item C<access>
 
@@ -110,8 +115,13 @@ L<Math::Trig>.
 
 =item C<alarm>
 
-This is identical to Perl's builtin C<alarm()> function,
-either for arming or disarming the C<SIGARLM> timer.
+This is identical to Perl's builtin C<alarm()> function, either for arming or
+disarming the C<SIGARLM> timer, except that C<POSIX::alarm()> must be provided
+an explicit value (rather than relying on an implicit C<$_>):
+
+    POSIX::alarm(3)     # good
+
+    POSIX::alarm()      # throws exception
 
 =item C<asctime>
 
@@ -203,13 +213,27 @@ integer value greater than or equal to the given numerical argument.
 
 =item C<chdir>
 
-This is identical to Perl's builtin C<chdir()> function, allowing
-one to change the working (default) directory, see L<perlfunc/chdir>.
+This is identical to Perl's builtin C<chdir()> function, allowing one to
+change the working (default) directory -- see L<perlfunc/chdir> -- with the
+exception that C<POSIX::chdir()> must be provided an explicit value (rather
+than relying on an implicit C<$_>):
+
+    $rv = POSIX::chdir('path/to/dir');      # good
+
+    $rv = POSIX::chdir();                   # throws exception
 
 =item C<chmod>
 
 This is identical to Perl's builtin C<chmod()> function, allowing
-one to change file and directory permissions, see L<perlfunc/chmod>.
+one to change file and directory permissions -- see L<perlfunc/chmod> -- with
+the exception that C<POSIX::chmod()> can only change one file at a time
+(rather than a list of files):
+
+    $c = chmod 0664, $file1, $file2;          # good
+
+    $c = POSIX::chmod 0664, $file1;           # throws exception
+
+    $c = POSIX::chmod 0664, $file1, $file2;   # throws exception
 
 =item C<chown>
 
@@ -960,13 +984,13 @@ POSIX.1-2008 and are only available on systems that support them.
 This is identical to Perl's builtin C<localtime()> function for
 converting seconds since the epoch to a date see L<perlfunc/localtime> except
 that C<POSIX::localtime()> must be provided an explicit value (rather than
-relying an implicit C<$_>:
+relying on an implicit C<$_>):
 
-    @localtime = POSIX::localtime(time);    # Good
+    @localtime = POSIX::localtime(time);    # good
 
-    @localtime = localtime();               # Good
+    @localtime = localtime();               # good
 
-    @localtime = POSIX::localtime();        # Throws exception
+    @localtime = POSIX::localtime();        # throws exception
 
 =item C<log>
 
diff --git a/ext/POSIX/t/usage.t b/ext/POSIX/t/usage.t
index 4d900e7680..8aba55c9cb 100644
--- a/ext/POSIX/t/usage.t
+++ b/ext/POSIX/t/usage.t
@@ -32,10 +32,10 @@ foreach my $func (sort @all) {
     my $arg_pat = join ', ', ('[a-z]+') x $valid{$func};
     my $expect = qr/\AUsage: POSIX::$func\($arg_pat\) at \(eval/;
     foreach my $try (@try) {
-	next if $valid{$func} == $try;
-	my $call = "POSIX::$func(" . join(', ', 1 .. $try) . ')';
-	is(eval "$call; 1", undef, "$call fails");
-	like($@, $expect, "POSIX::$func for $try arguments gives expected error")
+	    next if $valid{$func} == $try;
+	    my $call = "POSIX::$func(" . join(', ', 1 .. $try) . ')';
+	    is(eval "$call; 1", undef, "$call fails");
+	    like($@, $expect, "POSIX::$func for $try arguments gives expected error")
     }
 }