@@ -1,15 +1,16 @@
 # Module 'stat'
-
+#
 # Defines constants and functions for interpreting stat/lstat struct
-# as returned by posix.stat() and posix.lstat() (if it exists).
-
-# XXX This module may have to be adapted for UNIXoid systems whose
-# <sys/stat.h> deviates from AT&T or BSD UNIX; their S_IF* constants
-# may differ.
-
+# as returned by os.stat() and os.lstat() (if it exists).
+#
 # Suggested usage: from stat import *
+#
+# XXX Strictly spoken, this module may have to be adapted for each POSIX
+# implementation; in practice, however, the numeric constants used by
+# stat() are almost universal (even for stat() emulations on non-UNIX
+# systems like Macintosh or MS-DOS).
 
-# Tuple indices for stat struct members
+# Indices for stat struct members in tuple returned by os.stat()
 
 ST_MODE  = 0
 ST_INO   = 1
@@ -22,10 +23,16 @@
 ST_MTIME = 8
 ST_CTIME = 9
 
+# Extract bits from the mode
+
 def S_IMODE(mode):
-	return mode%4096
+	return mode & 07777
+
 def S_IFMT(mode):
-	return mode - mode%4096
+	return mode & ~07777
+
+# Constants used as S_IFMT() for various file types
+# (not all are implemented on all systems)
 
 S_IFDIR  = 0040000
 S_IFCHR  = 0020000
@@ -35,6 +42,8 @@ def S_IFMT(mode):
 S_IFLNK  = 0120000
 S_IFSOCK = 0140000
 
+# Functions to test for each file type
+
 def S_ISDIR(mode):
 	return S_IFMT(mode) == S_IFDIR