Apply suggestions from code review

Co-authored-by: Brett Cannon <brett@python.org>
python · miss-islington · Jul 22, 2022 · May 8, 2022 · May 9, 2022 · May 9, 2022
commit 15d96b99db69e65f6210f813335fab808bdeda12
@@ -952,24 +952,24 @@ call fails (for example because the path doesn't exist).
    either top-down or bottom-up.
 
    For each directory in the directory tree rooted at *self* (including
-   *self* but excluding '.' and '..'), yields a 3-tuple
+   *self* but excluding '.' and '..'), the method yields a 3-tuple of
    ``(dirpath, dirnames, filenames)``
 
-   *dirpath* is a :class:`Path` to the directory, *dirnames* is a list of the names
-   of the subdirectories in *dirpath* (excluding ``'.'`` and ``'..'``), and
-   *filenames* is a list of the names of the non-directory files in *dirpath*.
-   Note that the names in the lists contain no path components. To get a full
-   path (which begins with *self*) to a file or directory in *dirpath*, do
-   ``dirpath / name``. Whether or not the lists are sorted depends on the file
-   system.
+   *dirpath* is a :class:`Path` to the directory currently being walked,
+   *dirnames* is a list of strings for the names of subdirectories in *dirpath*
+   (excluding ``'.'`` and ``'..'``), and *filenames* is a list of strings for
+   the names of the non-directory files in *dirpath*. To get a full path
+   (which begins with *self*) to a file or directory in *dirpath*, do
+   ``dirpath / name``. Whether or not the lists are sorted is file
+   system-dependent.
 
    If optional argument *top_down* is ``True`` or not specified, the triple for a
    directory is generated before the triples for any of its subdirectories
-   (directories are generated top-down).  If *top_down* is ``False``, the triple
+   (directories are walked top-down).  If *top_down* is ``False``, the triple
    for a directory is generated after the triples for all of its subdirectories
    (directories are generated bottom-up). No matter the value of *top_down*, the
    list of subdirectories is retrieved before the tuples for the directory and
-   its subdirectories are generated.
+   its subdirectories are walked.
 
    When *top_down* is True, the caller can modify the *dirnames* list in-place
    (For example, using :keyword:`del` or slice assignment), and :meth:`Path.walk`
@@ -981,42 +981,41 @@ call fails (for example because the path doesn't exist).
    directories in *dirnames* have already been generated by the time *dirnames*
    is yielded to the caller.
 
-   By default errors from :func:`os.scandir` call are ignored.  If
+   By default, errors from :func:`os.scandir` are ignored.  If the
    optional argument *on_error* is specified, it should be a callable; it
    will be called with one argument, an :exc:`OSError` instance. It can
    report the error to continue with the walk, or raise the exception
    to abort the walk. Note that the filename is available as the
    ``filename`` attribute of the exception object.
 
-   By default, :meth:`Path.walk` will not walk down into symbolic links that
+   By default, :meth:`Path.walk` will not follow symbolic links that
    resolve to directories.  Set *follow_symlinks* to ``True`` to visit directories
-   pointed to by symlinks, on systems that support them.
+   pointed to by symlinks (where supported).
 
    .. note::
 
       Be aware that setting *follow_symlinks* to ``True`` can lead to infinite
       recursion if a link points to a parent directory of itself. :meth:`Path.walk`
-      does not keep track of the directories it visited already.
+      does not keep track of the directories it has already visited.
 
    .. note::
-      This method assumes that the current working directory is not changing while
+      This method assumes that the current working directory does not change while
       walking relative paths.
-   .. note::
 
-      :meth:`Path.walk` assumes the directories have not been modified between
-      its resumptions. For example, if a directory from *dirnames* has been replaced
+   .. note::
+      :meth:`Path.walk` assumes the directories it walks are not been modified during
+      execution. For example, if a directory from *dirnames* has been replaced
       with a symlink and *follow_symlinks* = ``False``, :meth:`Path.walk` will
       still try to descend into it. To prevent such behavior, remove directories
-      from *dirnames* if they have been modified and you do not want to
-      descend into them anymore.
+      from *dirnames* as appropriate.
 
    .. note::
 
-      Unlike :func:`os.walk`, :meth:`Path.walk` adds symlinks to directories into *filenames*
-      if *follow_symlinks* is ``True``
+      Unlike :func:`os.walk`, :meth:`Path.walk` lists symlinks to directories into
+      *filenames* if *follow_symlinks* is ``True``.
 
-   This example displays the number of bytes taken by non-directory files in each
-   directory under the starting directory, except that it doesn't look under any
+   This example displays the number of bytes used by all files in each directory,
+   while ignoring `__pycache__` directories.
    :file:`__pycache__` subdirectory::
 
       from pathlib import Path
@@ -1032,14 +1031,14 @@ call fails (for example because the path doesn't exist).
         if '__pycache__' in dirs:
               dirs.remove('__pycache__')
 
-   In the next example (simple implementation of :func:`shutil.rmtree`),
-   walking the tree bottom-up is essential, :func:`rmdir` doesn't allow
-   deleting a directory before the directory is empty::
+   This next example is asimple implementation of :func:`shutil.rmtree`.
+   Walking the tree bottom-up is essential as :func:`rmdir` doesn't allow
+   deleting a directory before it is empty::
 
       # Delete everything reachable from the directory "top",
       # assuming there are no symbolic links.
       # CAUTION:  This is dangerous!  For example, if top == Path('/'),
-      # it could delete all your disk files.
+      # it could delete all of your files.
       for root, dirs, files in top.walk(topdown=False):
           for name in files:
               (root / name).unlink()