#10111: minor problems in 2.7 FILE* API docs.

2 files changed, 16 insertions, 5 deletions

diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst
index 5d74355..bdb8c49 100644
--- a/Doc/c-api/file.rst
+++ b/Doc/c-api/file.rst
@@ -63,7 +63,7 @@ change in future releases of Python.
    Return the file object associated with *p* as a :ctype:`FILE\*`.
 
    If the caller will ever use the returned :ctype:`FILE\*` object while
-   the GIL is released it must also call the :cfunc:`PyFile_IncUseCount` and
+   the :term:`GIL` is released it must also call the :cfunc:`PyFile_IncUseCount` and
    :cfunc:`PyFile_DecUseCount` functions described below as appropriate.
 
 
@@ -76,10 +76,19 @@ change in future releases of Python.
    finished with the :ctype:`FILE\*`.  Otherwise the file object will
    never be closed by Python.
 
-   The GIL must be held while calling this function.
+   The :term:`GIL` must be held while calling this function.
 
-   The suggested use is to call this after :cfunc:`PyFile_AsFile` just before
-   you release the GIL.
+   The suggested use is to call this after :cfunc:`PyFile_AsFile` and before
+   you release the GIL::
+
+      FILE *fp = PyFile_AsFile(p);
+      PyFile_IncUseCount(p);
+      /* ... */
+      Py_BEGIN_ALLOW_THREADS
+      do_something(fp);
+      Py_END_ALLOW_THREADS
+      /* ... */
+      PyFile_DecUseCount(p);
 
    .. versionadded:: 2.6
 
@@ -90,7 +99,8 @@ change in future releases of Python.
    indicate that the caller is done with its own use of the :ctype:`FILE\*`.
    This may only be called to undo a prior call to :cfunc:`PyFile_IncUseCount`.
 
-   The GIL must be held while calling this function.
+   The :term:`GIL` must be held while calling this function (see the example
+   above).
 
    .. versionadded:: 2.6
 
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index 79c96e4..f8ab642 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -413,6 +413,7 @@ Thread State and the Global Interpreter Lock
 ============================================
 
 .. index::
+   single: GIL
    single: global interpreter lock
    single: interpreter lock
    single: lock, interpreter