gh-160322: document shutil.rmtree("link/") symlink following behavior

Author: gpshead

Doc/library/shutil.rst

@@ -316,6 +316,13 @@ Directory and files operations
    handled by calling a handler specified by *onexc* or *onerror* or, if both
    are omitted, exceptions are propagated to the caller.
 
+   As with other path-based functions, a trailing path separator makes *path*
+   refer to the directory that a symbolic link points to rather than to the
+   link itself.  For example, ``rmtree('link/')`` deletes the contents of the
+   directory that ``link`` points to, then reports an error when it tries to
+   remove ``link/`` itself.  The link and the now-empty directory are left in
+   place.
+
    This function can support :ref:`paths relative to directory descriptors
    <dir_fd>`.