[pypy-commit] pypy default: update the docstrings

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: 
Changeset: r75489:96024f66d2d8
Date: 2015-01-23 10:25 +0100
http://bitbucket.org/pypy/pypy/changeset/96024f66d2d8/

Log:	update the docstrings

diff --git a/rpython/rlib/rposix.py b/rpython/rlib/rposix.py
--- a/rpython/rlib/rposix.py
+++ b/rpython/rlib/rposix.py
@@ -97,14 +97,22 @@
                                          _nowrapper=True, c_type='int')
 
 def get_saved_errno():
-    """Return the saved value of the errno.  This value is saved after a call
-    to an llexternal function with 'save_err & RFFI_ERRNO_AFTER != 0'."""
+    """Return the value of the "saved errno".
+    This value is saved after a call to a C function, if it was declared
+    with the flag llexternal(..., save_err=rffi.RFFI_SAVE_ERRNO).
+    Functions without that flag don't change the saved errno.
+    """
     from rpython.rlib import rthread
     return intmask(rthread.tlfield_rpy_errno.getraw())
 
 def set_saved_errno(errno):
-    """Set the saved value of the errno.  This value will be used by a
-    following llexternal function with 'save_err & RFFI_ERRNO_BEFORE != 0'."""
+    """Set the value of the saved errno.  This value will be used to
+    initialize the real errno just before calling the following C function,
+    provided it was declared llexternal(..., save_err=RFFI_READSAVED_ERRNO).
+    Note also that it is more common to want the real errno to be initially
+    zero; for that case, use llexternal(..., save_err=RFFI_ZERO_ERRNO_BEFORE)
+    and then you don't need set_saved_errno(0).
+    """
     from rpython.rlib import rthread
     rthread.tlfield_rpy_errno.setraw(rffi.cast(INT, errno))
 
diff --git a/rpython/rlib/rwin32.py b/rpython/rlib/rwin32.py
--- a/rpython/rlib/rwin32.py
+++ b/rpython/rlib/rwin32.py
@@ -124,10 +124,24 @@
                                 _nowrapper=True, sandboxsafe=True)
 
     def GetLastError_saved():
+        """Return the value of the "saved LastError".
+        The C-level GetLastError() is saved there after a call to a C
+        function, if that C function was declared with the flag
+        llexternal(..., save_err=rffi.RFFI_SAVE_LASTERROR).
+        Functions without that flag don't change the saved LastError.
+        Alternatively, if the function was declared RFFI_SAVE_WSALASTERROR,
+        then the value of the C-level WSAGetLastError() is saved instead
+        (into the same "saved LastError" variable).
+        """
         from rpython.rlib import rthread
         return rffi.cast(lltype.Signed, rthread.tlfield_rpy_lasterror.getraw())
 
     def SetLastError_saved(err):
+        """Set the value of the saved LastError.  This value will be used in
+        a call to the C-level SetLastError() just before calling the
+        following C function, provided it was declared
+        llexternal(..., save_err=RFFI_READSAVED_LASTERROR).
+        """
         from rpython.rlib import rthread
         rthread.tlfield_rpy_lasterror.setraw(rffi.cast(DWORD, err))