From 5ce2fecf8edfcb1c8210f1a3da83e0cef7b1fa50 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Martin=20v=2E=20L=C3=B6wis?= <martin@v.loewis.de>
Date: Thu, 6 Nov 2003 21:08:11 +0000
Subject: Patch #837322: Clarify owning, borrowing, stealing. Backported to
 2.3.

---
 Doc/api/intro.tex | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/Doc/api/intro.tex b/Doc/api/intro.tex
index ccbe686..364487d 100644
--- a/Doc/api/intro.tex
+++ b/Doc/api/intro.tex
@@ -169,12 +169,16 @@ becomes second nature.
 \subsubsection{Reference Count Details \label{refcountDetails}}
 
 The reference count behavior of functions in the Python/C API is best 
-explained in terms of \emph{ownership of references}.  Note that we 
-talk of owning references, never of owning objects; objects are always 
-shared!  When a function owns a reference, it has to dispose of it 
-properly --- either by passing ownership on (usually to its caller) or 
-by calling \cfunction{Py_DECREF()} or \cfunction{Py_XDECREF()}.  When
-a function passes ownership of a reference on to its caller, the
+explained in terms of \emph{ownership of references}.  Ownership
+pertains to references, never to objects (objects are not owned: they
+are always shared).  "Owning a reference" means being responsible for
+calling Py_DECREF on it when the reference is no longer needed. 
+Ownership can also be transferred, meaning that the code that receives
+ownership of the reference then becomes responsible for eventually
+decref'ing it by calling \cfunction{Py_DECREF()} or
+\cfunction{Py_XDECREF()} when it's no longer needed --or passing on
+this responsibility (usually to its caller).
+When a function passes ownership of a reference on to its caller, the
 caller is said to receive a \emph{new} reference.  When no ownership
 is transferred, the caller is said to \emph{borrow} the reference.
 Nothing needs to be done for a borrowed reference.
-- 
cgit v0.12

