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 1490eed..036664e 100644
--- a/Doc/api/newtypes.tex
+++ b/Doc/api/newtypes.tex
@@ -1645,7 +1645,9 @@
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 @@
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}