Some docs for the assertions.

p4raw-id: //depot/perl@19808

5 files changed, 39 insertions, 36 deletions

diff --git a/lib/assertions.pm b/lib/assertions.pm
index 7af0fb0994..700abf46bb 100644
--- a/lib/assertions.pm
+++ b/lib/assertions.pm
@@ -118,9 +118,6 @@ sub import {
     $^H |= $hint|$seen_hint;
 }
 
-
-
-
 sub unimport {
     $^H &= ~$hint;
 }
@@ -131,7 +128,7 @@ __END__
 
 =head1 NAME
 
-assertions - selects assertions
+assertions - select assertions in blocks of code
 
 =head1 SYNOPSIS
 
@@ -142,12 +139,12 @@ assertions - selects assertions
 
   {
       use assertions qw( foo bar );
-      assert { print "asserting 'foo' & 'bar'\n" };
+      assert { print "asserting 'foo' and 'bar'\n" };
   }
 
   {
       use assertions qw( bar );
-      assert { print "asserting 'bar'\n" };
+      assert { print "asserting only 'bar'\n" };
   }
 
   {
@@ -157,24 +154,23 @@ assertions - selects assertions
 
   assert { print "asserting 'foo' again\n" };
 
-
-=head1 ABSTRACT
-
-C<assertions> pragma selects the tags used to control assertion
-execution.
-
 =head1 DESCRIPTION
 
+The C<assertions> pragma specifies the tags used to enable and disable
+the execution of assertion subroutines.
 
+An assertion subroutine is declared with the C<:assertion> attribute.
+This subroutine is not normally executed : it's optimized away by perl
+at compile-time.
 
-
-=head2 EXPORT
-
-None by default.
+The C<assertion> pragma associates to its lexical scope one or several
+assertion tags. Then, to activate the execution of the assertions
+subroutines in this scope, these tags must be given to perl via the
+B<-A> command-line option.
 
 =head1 SEE ALSO
 
-
+L<perlrun>.
 
 =head1 AUTHOR
 
@@ -188,3 +184,5 @@ This library is free software; you can redistribute it and/or modify
 it under the same terms as Perl itself.
 
 =cut
+
+TODO : Some more docs are to be added about assertion expressions.
diff --git a/lib/assertions/activate.pm b/lib/assertions/activate.pm
index 0ce73f3316..198b8368a6 100644
--- a/lib/assertions/activate.pm
+++ b/lib/assertions/activate.pm
@@ -2,13 +2,10 @@ package assertions::activate;
 
 our $VERSION = '0.01';
 
-# use strict;
-# use warnings;
-
 sub import {
     shift;
-    @_='.*' unless @_;
-    push @{^ASSERTING}, ( map { qr/^(?:$_)$/ } @_) ;
+    @_ = '.*' unless @_;
+    push @{^ASSERTING}, map { qr/^(?:$_)\z/ } @_;
 }
 
 1;
@@ -16,28 +13,27 @@ __END__
 
 =head1 NAME
 
-assertions::activate - assertions activation
+assertions::activate - activate assertions
 
 =head1 SYNOPSIS
 
-  use assertions::activate 'Foo', 'bar', 'Foo::boz::.*' ;
-
-=head1 ABSTRACT
+  use assertions::activate 'Foo', 'bar', 'Foo::boz::.*';
 
-C<assertions::activate> module is used to configure assertion
-execution.
+  # activate all assertions
+  use assertions::activate;
 
 =head1 DESCRIPTION
 
+This module is used internally by perl (and its C<-A> command-line switch) to
+enable and disable assertions. It can also be used directly.
 
-
-=head2 EXPORT
-
-None by default.
+The import parameters are a list of strings or of regular expressions. The
+assertion tags that match those regexps are enabled. If no parameter is
+given, all assertions are activated.
 
 =head1 SEE ALSO
 
-L<assertions>
+L<assertions>, L<perlrun>.
 
 =head1 AUTHOR
 
diff --git a/pod/perllexwarn.pod b/pod/perllexwarn.pod
index 8ee7fc3248..9b614271bb 100644
--- a/pod/perllexwarn.pod
+++ b/pod/perllexwarn.pod
@@ -207,6 +207,8 @@ The current hierarchy is:
 
   all -+
        |
+       +- assertions
+       |
        +- closure
        |
        +- deprecated
diff --git a/pod/perlrun.pod b/pod/perlrun.pod
index 85d3bdf7b4..c33c478305 100644
--- a/pod/perlrun.pod
+++ b/pod/perlrun.pod
@@ -14,7 +14,8 @@ B<perl>	S<[ B<-sTtuUWX> ]>
 	S<[ B<-x>[I<dir>] ]>
 	S<[ B<-i>[I<extension>] ]>
 	S<[ B<-e> I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
-	S<[ B<-C [I<number/list>] >]> ]>
+	S<[ B<-A [I<assertions>] >]>
+	S<[ B<-C [I<number/list>] >]>
 
 =head1 DESCRIPTION
 
@@ -253,6 +254,12 @@ format: C<-0xHHH...>, where the C<H> are valid hexadecimal digits.
 (This means that you cannot use the C<-x> with a directory name that
 consists of hexadecimal digits.)
 
+=item B<-A [I<assertions>]>
+
+Activates the assertions given after the switch as a comma-separated
+list of assertion names. If no assertion name is given, activates all
+assertions. See L<assertions>.
+
 =item B<-a>
 
 turns on autosplit mode when used with a B<-n> or B<-p>.  An implicit
diff --git a/t/run/switch_A.t b/t/run/switch_A.t
index 5a71b409a5..4204e64023 100755
--- a/t/run/switch_A.t
+++ b/t/run/switch_A.t
@@ -3,7 +3,7 @@
 BEGIN {
     chdir 't' if -d 't';
     unshift @INC, '../lib';
-    require './test.pl';	# for which_perl() etc
+    require './test.pl';
 }
 
 BEGIN {
@@ -13,7 +13,7 @@ BEGIN {
 #1
 fresh_perl_is('sub cm : assertion { "ok" }; use assertions Hello; print cm()',
 	      'ok',
-	      { switches => ['-AHello'] }, '-A');
+	      { switches => ['-AHello'] }, '-AHello');
 
 #2
 fresh_perl_is('sub cm : assertion { "ok" }; use assertions SDFJKS; print cm()',