Improve docs for lastparen, lastcloseparen

There's lots of confusion here, especially about lastparen - some of
the docs are just plain wrong.

3 files changed, 19 insertions, 7 deletions

diff --git a/pod/perlreapi.pod b/pod/perlreapi.pod
index 2df337e21a..c32171a9a9 100644
--- a/pod/perlreapi.pod
+++ b/pod/perlreapi.pod
@@ -710,9 +710,10 @@ used in the future for all engines for optimisations.
 
 =head2 C<nparens>, C<lastparen>, and C<lastcloseparen>
 
-These fields are used to keep track of how many paren groups could be matched
-in the pattern, which was the last open paren to be entered, and which was
-the last close paren to be entered.
+These fields are used to keep track of: how many paren capture groups
+there are in the pattern; which was the highest paren to be closed (see
+L<perlvar/$+>); and which was the most recent paren to be closed (see
+L<perlvar/$^N>).
 
 =head2 C<intflags>
 
diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index c7b77120ef..114a7e0d12 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -1046,7 +1046,10 @@ This variable is read-only and dynamically-scoped.
 =item $+
 X<$+> X<$LAST_PAREN_MATCH>
 
-The text matched by the last bracket of the last successful search pattern.
+The text matched by the highest used capture group of the last
+successful search pattern.  It is logically equivalent to the highest
+numbered capture variable (C<$1>, C<$2>, ...) which has a defined value.
+
 This is useful if you don't know which one of a set of alternative patterns
 matched.  For example:
 
@@ -1063,7 +1066,15 @@ X<$^N> X<$LAST_SUBMATCH_RESULT>
 
 The text matched by the used group most-recently closed (i.e. the group
 with the rightmost closing parenthesis) of the last successful search
-pattern.
+pattern. This is subtly different from C<$+>. For example in
+
+    "ab" =~ /^((.)(.))$/
+
+we have
+
+    $1,$^N   have the value "ab"
+    $2       has  the value "a"
+    $3,$+    have the value "b"
 
 This is primarily used inside C<(?{...})> blocks for examining text
 recently matched.  For example, to effectively capture text to a variable
diff --git a/regexp.h b/regexp.h
index 44409f0d9c..aa31846cbb 100644
--- a/regexp.h
+++ b/regexp.h
@@ -134,8 +134,8 @@ typedef struct regexp {
      * Data about the last/current match. These are modified during matching
      */
 
-    U32 lastparen;           /* last open paren matched */
-    U32 lastcloseparen;      /* last close paren matched */
+    U32 lastparen;           /* highest close paren matched ($+) */
+    U32 lastcloseparen;      /* last close paren matched ($^N) */
     regexp_paren_pair *offs; /* Array of offsets for (@-) and (@+) */
     char **recurse_locinput; /* used to detect infinite recursion, XXX: move to internal */