Expand on the semantics of reload(). Closes #919099.

1 files changed, 24 insertions, 2 deletions

diff --git a/Doc/lib/libfuncs.tex b/Doc/lib/libfuncs.tex
index 11a8ba5..e5d9923 100644
--- a/Doc/lib/libfuncs.tex
+++ b/Doc/lib/libfuncs.tex
@@ -785,14 +785,36 @@ class C(object):
 \end{funcdesc}
 
 \begin{funcdesc}{reload}{module}
-  Re-parse and re-initialize an already imported \var{module}.  The
+  Reload a previously imported \var{module}.  The
   argument must be a module object, so it must have been successfully
   imported before.  This is useful if you have edited the module
   source file using an external editor and want to try out the new
   version without leaving the Python interpreter.  The return value is
   the module object (the same as the \var{module} argument).
 
-  There are a number of caveats:
+  When \code{reload(module)} is executed:
+
+\begin{itemize}
+
+    \item{Python modules' code is recompiled and the module-level code
+    reexecuted, defining a new set of objects which are bound to names in
+    the module's dictionary.  The \code{init} function of extension
+    modules is not called a second time.}
+
+    \item{As with all other objects in Python the old objects are only
+    reclaimed after their reference counts drop to zero.}
+
+    \item{The names in the module namespace are updated to point to
+    any new or changed objects.}
+
+    \item{Other references to the old objects (such as names external
+    to the module) are not rebound to refer to the new objects and
+    must be updated in each namespace where they occur if that is
+    desired.}
+
+\end{itemize}
+
+  There are a number of other caveats:
 
   If a module is syntactically correct but its initialization fails,
   the first \keyword{import} statement for it does not bind its name