#10960: fix 'stat' links, link to lstat from stat, general tidy of stat doc.

Original patch by Michal Nowikowski, with some additions and wording
fixes by me.

I changed the wording from 'Performs a stat system call' to 'Performs
the equivalent of a stat system call', since on Windows there are no
stat/lstat system calls involved.  I also extended Michal's breakout
of the attributes into a list to the other paragraphs, and rearranged
the order of the paragraphs in the 'stat' docs to make it flow
better and put it in what I think is a more logical/useful order.

Doc/ACKS.txt

@@ -140,6 +140,7 @@ docs@python.org), and we'll be glad to correct the problem.
    * Ross Moore
    * Sjoerd Mullender
    * Dale Nagata
+   * Michal Nowikowski 
    * Ng Pheng Siong
    * Koray Oner
    * Tomas Oppelstrup

Doc/library/os.rst

@@ -657,7 +657,7 @@ as internal buffering of data.
 
 .. function:: fstat(fd)
 
-   Return status for file descriptor *fd*, like :func:`stat`.
+   Return status for file descriptor *fd*, like :func:`~os.stat`.
 
    Availability: Unix, Windows.
 
@@ -1080,8 +1080,10 @@ Files and Directories
 
 .. function:: lstat(path)
 
-   Like :func:`stat`, but do not follow symbolic links.  This is an alias for
+   Perform the equivalent of an :c:func:`lstat` system call on the given path.
-   :func:`stat` on platforms that do not support symbolic links.
+   Similar to :func:`~os.stat`, but does not follow symbolic links.  On
+   platforms that do not support symbolic links, this is an alias for
+   :func:`~os.stat`.
 
    .. versionchanged:: 3.2
       Added support for Windows 6.0 (Vista) symbolic links.
@@ -1276,46 +1278,43 @@ Files and Directories
 
 .. function:: stat(path)
 
-   Perform a :c:func:`stat` system call on the given path.  The return value is an
+   Perform the equivalent of a :c:func:`stat` system call on the given path.
-   object whose attributes correspond to the members of the :c:type:`stat`
+   (This function follows symlinks; to stat a symlink use :func:`lstat`.)
-   structure, namely: :attr:`st_mode` (protection bits), :attr:`st_ino` (inode
-   number), :attr:`st_dev` (device), :attr:`st_nlink` (number of hard links),
-   :attr:`st_uid` (user id of owner), :attr:`st_gid` (group id of owner),
-   :attr:`st_size` (size of file, in bytes), :attr:`st_atime` (time of most recent
-   access), :attr:`st_mtime` (time of most recent content modification),
-   :attr:`st_ctime` (platform dependent; time of most recent metadata change on
-   Unix, or the time of creation on Windows)::
 
-      >>> import os
+   The return value is an object whose attributes correspond to the members
-      >>> statinfo = os.stat('somefile.txt')
+   of the :c:type:`stat` structure, namely:
-      >>> statinfo
+
-      (33188, 422511, 769, 1, 1032, 100, 926, 1105022698,1105022732, 1105022732)
+   * :attr:`st_mode` - protection bits,
-      >>> statinfo.st_size
+   * :attr:`st_ino` - inode number,
-      926
+   * :attr:`st_dev` - device,
+   * :attr:`st_nlink` - number of hard links,
+   * :attr:`st_uid` - user id of owner,
+   * :attr:`st_gid` - group id of owner,
+   * :attr:`st_size` - size of file, in bytes,
+   * :attr:`st_atime` - time of most recent access,
+   * :attr:`st_mtime` - time of most recent content modification,
+   * :attr:`st_ctime` - platform dependent; time of most recent metadata change on
+     Unix, or the time of creation on Windows)
 
    On some Unix systems (such as Linux), the following attributes may also be
-   available: :attr:`st_blocks` (number of blocks allocated for file),
+   available:
-   :attr:`st_blksize` (filesystem blocksize), :attr:`st_rdev` (type of device if an
+
-   inode device). :attr:`st_flags` (user defined flags for file).
+   * :attr:`st_blocks` - number of blocks allocated for file
+   * :attr:`st_blksize` - filesystem blocksize
+   * :attr:`st_rdev` - type of device if an inode device
+   * :attr:`st_flags` - user defined flags for file
 
    On other Unix systems (such as FreeBSD), the following attributes may be
-   available (but may be only filled out if root tries to use them): :attr:`st_gen`
+   available (but may be only filled out if root tries to use them):
-   (file generation number), :attr:`st_birthtime` (time of file creation).
+
+   * :attr:`st_gen` - file generation number
+   * :attr:`st_birthtime` - time of file creation
 
    On Mac OS systems, the following attributes may also be available:
-   :attr:`st_rsize`, :attr:`st_creator`, :attr:`st_type`.
 
-   .. index:: module: stat
+   * :attr:`st_rsize`
-
+   * :attr:`st_creator`
-   For backward compatibility, the return value of :func:`stat` is also accessible
+   * :attr:`st_type`
-   as a tuple of at least 10 integers giving the most important (and portable)
-   members of the :c:type:`stat` structure, in the order :attr:`st_mode`,
-   :attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`, :attr:`st_uid`,
-   :attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`, :attr:`st_mtime`,
-   :attr:`st_ctime`. More items may be added at the end by some implementations.
-   The standard module :mod:`stat` defines functions and constants that are useful
-   for extracting information from a :c:type:`stat` structure. (On Windows, some
-   items are filled with dummy values.)
 
    .. note::
 
@@ -1325,13 +1324,35 @@ Files and Directories
       :attr:`st_mtime` has 2-second resolution, and :attr:`st_atime` has only 1-day
       resolution.  See your operating system documentation for details.
 
+   For backward compatibility, the return value of :func:`~os.stat` is also accessible
+   as a tuple of at least 10 integers giving the most important (and portable)
+   members of the :c:type:`stat` structure, in the order :attr:`st_mode`,
+   :attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`, :attr:`st_uid`,
+   :attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`, :attr:`st_mtime`,
+   :attr:`st_ctime`. More items may be added at the end by some implementations.
+
+   .. index:: module: stat
+
+   The standard module :mod:`stat` defines functions and constants that are useful
+   for extracting information from a :c:type:`stat` structure. (On Windows, some
+   items are filled with dummy values.)
+
+   Example::
+
+      >>> import os
+      >>> statinfo = os.stat('somefile.txt')
+      >>> statinfo
+      (33188, 422511, 769, 1, 1032, 100, 926, 1105022698,1105022732, 1105022732)
+      >>> statinfo.st_size
+      926
+
    Availability: Unix, Windows.
 
 
 .. function:: stat_float_times([newvalue])
 
    Determine whether :class:`stat_result` represents time stamps as float objects.
-   If *newvalue* is ``True``, future calls to :func:`stat` return floats, if it is
+   If *newvalue* is ``True``, future calls to :func:`~os.stat` return floats, if it is
    ``False``, future calls return ints. If *newvalue* is omitted, return the
    current setting.
 
@@ -1428,8 +1449,8 @@ Files and Directories
    respectively. Whether a directory can be given for *path* depends on whether
    the operating system implements directories as files (for example, Windows
    does not).  Note that the exact times you set here may not be returned by a
-   subsequent :func:`stat` call, depending on the resolution with which your
+   subsequent :func:`~os.stat` call, depending on the resolution with which your
-   operating system records access and modification times; see :func:`stat`.
+   operating system records access and modification times; see :func:`~os.stat`.
 
    Availability: Unix, Windows.