Claifications: visit procs are supplied by the core, users aren't

expected to write their own.  A NULL "object" must not be passed to
the visit callback.  A non-zero return from a visit proc isn't
necessarily an error return (and it doesn't matter to the tp_traverse
code *what* it might signify, their only job is to return it).

diff --git a/Doc/api/newtypes.tex b/Doc/api/newtypes.tex
index 1490eedec8338128407f6491ba2e33f4fb11d0b1..036664e5ae21af0c32180ddef7737765ccc17f21 100644 (file)
--- a/Doc/api/newtypes.tex
+++ b/Doc/api/newtypes.tex
@@ -1645,7 +1645,9 @@ type:
   Type of the visitor function passed to the \member{tp_traverse}
   handler.  The function should be called with an object to traverse
   as \var{object} and the third parameter to the \member{tp_traverse}
-  handler as \var{arg}.
+  handler as \var{arg}.  The Python core uses several visitor functions
+  to implement cyclic garbage detection; it's not expected that users will
+  need to write their own visitor functions.
 \end{ctypedesc}
 
 The \member{tp_traverse} handler must have the following type:
@@ -1655,8 +1657,9 @@ The \member{tp_traverse} handler must have the following type:
   Traversal function for a container object.  Implementations must
   call the \var{visit} function for each object directly contained by
   \var{self}, with the parameters to \var{visit} being the contained
-  object and the \var{arg} value passed to the handler.  If
-  \var{visit} returns a non-zero value then an error has occurred and
+  object and the \var{arg} value passed to the handler.  The \var{visit}
+  function must not be called with a \NULL{} object argument.  If
+  \var{visit} returns a non-zero value
   that value should be returned immediately.
 \end{ctypedesc}