gh-94220: Align fnmatch docs with the implementation and amend markup (#114152)

- Align the argument spec for fnmatch functions with the actual
  implementation.
- Update Sphinx markup to recent recommandations.
- Add link to 'iterable' glossary entry.

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

1 files changed, 14 insertions, 12 deletions

diff --git a/Doc/library/fnmatch.rst b/Doc/library/fnmatch.rst
index aed8991..7cddecd 100644
--- a/Doc/library/fnmatch.rst
+++ b/Doc/library/fnmatch.rst
@@ -50,10 +50,10 @@ Also note that :func:`functools.lru_cache` with the *maxsize* of 32768 is used t
 cache the compiled regex patterns in the following functions: :func:`fnmatch`,
 :func:`fnmatchcase`, :func:`.filter`.
 
-.. function:: fnmatch(filename, pattern)
+.. function:: fnmatch(name, pat)
 
-   Test whether the *filename* string matches the *pattern* string, returning
-   :const:`True` or :const:`False`.  Both parameters are case-normalized
+   Test whether the filename string *name* matches the pattern string *pat*,
+   returning ``True`` or ``False``.  Both parameters are case-normalized
    using :func:`os.path.normcase`. :func:`fnmatchcase` can be used to perform a
    case-sensitive comparison, regardless of whether that's standard for the
    operating system.
@@ -69,22 +69,24 @@ cache the compiled regex patterns in the following functions: :func:`fnmatch`,
               print(file)
 
 
-.. function:: fnmatchcase(filename, pattern)
+.. function:: fnmatchcase(name, pat)
 
-   Test whether *filename* matches *pattern*, returning :const:`True` or
-   :const:`False`; the comparison is case-sensitive and does not apply
-   :func:`os.path.normcase`.
+   Test whether the filename string *name* matches the pattern string *pat*,
+   returning ``True`` or ``False``;
+   the comparison is case-sensitive and does not apply :func:`os.path.normcase`.
 
 
-.. function:: filter(names, pattern)
+.. function:: filter(names, pat)
 
-   Construct a list from those elements of the iterable *names* that match *pattern*. It is the same as
-   ``[n for n in names if fnmatch(n, pattern)]``, but implemented more efficiently.
+   Construct a list from those elements of the :term:`iterable` *names*
+   that match pattern *pat*.
+   It is the same as ``[n for n in names if fnmatch(n, pat)]``,
+   but implemented more efficiently.
 
 
-.. function:: translate(pattern)
+.. function:: translate(pat)
 
-   Return the shell-style *pattern* converted to a regular expression for
+   Return the shell-style pattern *pat* converted to a regular expression for
    using with :func:`re.match`.
 
    Example: