perlxs.pod: update 'SCOPE: Keyword' section

Author: iabyn

dist/ExtUtils-ParseXS/lib/perlxs.pod

@@ -1675,8 +1675,8 @@ it will be treated as the start of a new XSUB.
 =back
 
 The following file-scoped keywords are supported.  Note that the
-L<SCOPE|/The SCOPE: Keyword> can technically be a file-scoped keyword too,
-but is described further down as an XSUB keyword.
+L<SCOPE|/The SCOPE: Keyword and typemap entry> can technically be a
+file-scoped keyword too, but is described further down as an XSUB keyword.
 
 =head3 The REQUIRE: Keyword
 
@@ -2528,7 +2528,7 @@ L<PREINIT|/The PREINIT: Keyword> and L<INPUT|/The INPUT: Keyword>. The
 first allows you to inject extra variable declaration lines, while the
 latter used to be needed to specify the type of each parameter, but is now
 mainly of historical interest. This is also the place for the rarely-used
-L<SCOPE|/The SCOPE: Keyword> keyword.
+L<SCOPE|/The SCOPE: Keyword and typemap entry> keyword.
 
 Note that the keywords described in L<XSUB Generic Keywords> and L<Sharing
 XSUB bodies> may also appear in this part, plus the L<C_ARGS|/The C_ARGS:
@@ -2734,43 +2734,61 @@ C<INIT> blocks.
 
 =back
 
-=head3 The SCOPE: Keyword
-
-The SCOPE: keyword allows scoping to be enabled for a particular XSUB.
-Its effect is to wrap the main body of the XSUB (i.e. the C<CODE> or
-C<PPCODE> or implicit) with an C<ENTER> and C<LEAVE> pair. This has the
-effect of clearing any accumulated savestack entries at the end of the
-code body. It is disabled by default.
-
-The SCOPE keyword may appear either within the XSUB body (anywhere before
-a C<CODE:> could appear), or just before the XSUB declaration, but part of
-the same paragraph (i.e. no intervening blank lines). For example:
+=head3 The SCOPE: Keyword and typemap entry
 
+    # XSUB-scoped
     void
-    foo()
-      INPUT:
-        ...
-      PREINIT:
-        ...
+    foo(int i)
       SCOPE: ENABLE
       CODE:
         ...
 
+    # file-scoped
     SCOPE: ENABLE
     void
-    bar()
-      ...
+    bar(int i)
+      CODE:
+        ...
 
-The first form (within the XSUB body) has been available since perl-5.004,
-but was broken by perl-5.12.0 (xsubpp v2.21) and fixed in perl-5.44.0
-(xsubpp v3.58). The second form has been available since perl-5.12.0 .
+    # typemap entry
+    TYPEMAP: <<EOF
+    INPUT
+    T_MYINT
+       $var = my_int($arg); /* SCOPE */
+    EOF
 
-Note that to support potentially complex type mappings, if a typemap entry
-used by an XSUB contains a comment like C</* SCOPE */>, then scoping will
-be automatically enabled for any XSUB which uses that typemap entry for an
-C<INPUT> parameter. This currently only works for parameters whose type
-is specified in a separate C<INPUT> line rather than any ANSI-style
-declaration (C<foo(int i)>).
+The C<SCOPE> keyword can be used to enable scoping for a particular XSUB
+(disabled by default). Its effect is to wrap the main body of the XSUB
+(including most parameter and return value processing) within an C<{
+ENTER;> and C<LEAVE; }> pair. This has the effect of clearing any
+accumulated savestack entries at the end of the code body. If disabled,
+then the savestack will usually be cleared by the caller anyway, so this
+is a rarely-used keyword.
+
+The SCOPE keyword may be either XSUB-scoped or file-scoped (this refers to
+the scope of the keyword within the XS file, not to the scope generated by
+the keyword). For the first, it may appear anywhere in the input part or
+the XSUB. For the latter, it may appear anywhere in file scope, but due to
+a long-standing parser bug, the keyword's state is reset at the start of
+each XSUB, so it will only have any effect if appears just before a XSUB
+declaration and as part of the same paragraph (i.e. with no intervening
+blank lines), such as in the example above. It will only affect the single
+following XSUB.
+
+The XSUB-scoped form has been available since perl-5.004, but was broken
+by perl-5.12.0 (F<xsubpp> v2.21) and fixed in perl-5.44.0 (F<xsubpp>
+v3.58). The file-scoped form has been available since perl-5.12.0 .
+
+To support potentially complex type mappings, if an C<INPUT> typemap entry
+contains a code comment like C</* SCOPE */>, then scoping will be
+automatically enabled for any XSUB which uses that typemap entry. This
+currently only works for parameters whose type is specified using
+old-style C<INPUT> lines rather than an ANSI-style declaration, i.e. not
+for C<foo(int i)>. In fact, the XS parser, when looking for a SCOPE
+comment in a typemap, is currently very lax: it's actually a
+case-insensitive match of any code comment which contains the text "scope"
+plus anything else. But you shouldn't rely on this; always use the form
+shown here. Even better, just don't use it at all.
 
 =head2 The XSUB Init Part