Docs improvements

Doc/library/pathlib.rst

@@ -1182,17 +1182,17 @@ Querying file type and status
    A :class:`~pathlib.types.Status` object that supports querying file type
    information. The object exposes methods that cache their results, which can
    help reduce the number of system calls needed when switching on file type.
-   Care must be taken to avoid incorrectly using cached results::
-
-      >>> p = Path('setup.py')
-      >>> p.status.is_file()
-      True
-      >>> p.unlink()
-      >>> p.status.is_file()  # returns stale status
-      True
-      >>> p = Path(p)  # get fresh status
-      >>> p.status.is_file()
-      False
+   For example::
+
+      >>> p = Path('src')
+      >>> if p.status.is_symlink():
+      ...     print('symlink')
+      ... elif p.status.is_dir():
+      ...     print('directory')
+      ... else:
+      ...     print('other')
+      ...
+      directory
 
    The value is a :class:`os.DirEntry` instance if the path was generated by
    :meth:`Path.iterdir`. These objects are initialized with some information
@@ -1201,6 +1201,11 @@ Querying file type and status
    initially knows nothing about the file status. In either case, merely
    accessing :attr:`Path.status` does not perform any filesystem queries.
 
+   To fetch up-to-date information, it's best to use :meth:`Path.is_dir`,
+   :meth:`~Path.is_file` and :meth:`~Path.is_symlink` rather than this
+   attribute. There is no method to reset the cache; instead you can create
+   a new path object with an empty status cache via ``p = Path(p)``.
+
    .. versionadded:: 3.14