[3.15] gh-139580: Clarify pathlib full_match recursive pattern docs (GH-151479) (#159955)

gh-139580: Clarify pathlib full_match recursive pattern docs (GH-151479)

Documents how PurePath.full_match() handles a pattern ending in /**: /a/** matches /a/b but not /a, because the separator before ** must be present in the path and PurePath drops trailing slashes. Adds two doctest examples under full_match() and a note at the ** entry of the pattern language list contrasting it with Path.glob().
---------
(cherry picked from commit 2648604)

Co-authored-by: Harjoth Khara <harjoth.khara@gmail.com>
Co-authored-by: Terry J Reedy <tjreedy@udel.edu>

Author: 3 people

Doc/library/pathlib.rst

@@ -586,10 +586,23 @@ Pure paths provide the following methods and properties:
       True
       >>> PurePath('a/b.py').full_match('*.py')
       False
-      >>> PurePath('/a/b/c.py').full_match('/a/**')
-      True
       >>> PurePath('/a/b/c.py').full_match('**/*.py')
       True
+      >>> PurePath('/a/b/c.py').full_match('/a/**')
+      True
+
+   Patterns ending in "``/**``", as in the example above, may surprise when
+   passed to ``full_match``. Even though "``**``" can match 0 segments,
+   "``.../**``" requires a separator to match. Hence "``/a/**``" does not
+   match path "``/a``". Since :class:`PurePath` drops trailing slashes, this
+   pattern also does not match "``/a/``".
+
+   ::
+
+      >>> PurePath('/a').full_match('/a/**')
+      False
+      >>> PurePath('/a/').full_match('/a/**')
+      False
 
    .. seealso::
       :ref:`pathlib-pattern-language` documentation.
@@ -1810,6 +1823,8 @@ The following wildcards are supported in patterns for
 
 ``**`` (entire segment)
   Matches any number of file or directory segments, including zero.
+  Note that in :meth:`~PurePath.full_match`, "``a/**``" does not match
+  "``a``", whereas :meth:`~Path.glob` yields "``a``" for that pattern.
 ``*`` (entire segment)
   Matches one file or directory segment.
 ``*`` (part of a segment)