-builtin compatible ref example in Python docs

Doc/Manual/Python.html

@@ -5329,10 +5329,18 @@ wheel size: 135019664
 What has happened here is the garbage collector has collected the <tt>Bike</tt> instance as it doesn't think it is needed any more.
 The proxy instance, <tt>wheel</tt>, contains a reference to memory that was deleted when the <tt>Bike</tt> instance was collected.
 In order to prevent the garbage collector from collecting the <tt>Bike</tt> instance, a reference to the <tt>Bike</tt> must
-be added to the <tt>wheel</tt> instance. You can do this by adding the reference when the <tt>getWheel()</tt> method
+be added to the <tt>wheel</tt> instance. 
-is called using the typemap-like <tt>%pythonappend</tt> directive (see <a href="#Python_nn42">36.6.2 Adding additional Python code</a>):
+</p>
+    
+<p>
+You can do this by adding the reference when the <tt>getWheel()</tt> method
+is called using one of two approaches:
+</p>
+    
+<p>
+The easier, but less optimized, way is to use the typemap-like <tt>%pythonappend</tt> directive 
+(see <a href="#Python_nn42">36.6.2 Adding additional Python code</a>):
 </p>
-
 
 <div class="code">
 <pre>
@@ -5349,6 +5357,41 @@ The code gets appended to the Python code generated for the
 instance onto the <tt>Wheel</tt> proxy instance before it is returned to the 
 caller.
 </p>
+    
+<p>
+The second option, which performs better and is required if you use the 
+<tt>-builtin</tt> option, is to set the reference in the CPython implementation:
+    
+<div class="code">
+<pre>
+%fragment("extra_reference", "header") {
+
+static PyObject *extra_reference() {
+  static PyObject *extra_reference_string = NULL;
+  if (!extra_reference_string)
+    extra_reference_string = SWIG_Python_str_FromChar("_extra_reference");
+  return extra_reference_string;
+}
+
+}
+
+%extend Wheel {
+%typemap(ret, fragment="extra_reference") Wheel& getWheel %{
+  // A reference to the parent class is added to ensure the underlying C++
+  // object is not deleted while the item is in use
+  PyObject_SetAttr($result, extra_reference(), $self);
+%}
+/* FYI: Alternative approach, but is possibly harder to understand, so suggest above
+%typemap(out, fragment="extra_reference") Wheel& getWheel %{
+  $typemap(out, Wheel &)
+  // A reference to the parent class is added to ensure the underlying C++
+  // object is not deleted while the item is in use
+  PyObject_SetAttr($result, extra_reference(), $self);
+%}
+*/
+}
+</pre>
+</div>
 
 
 <H2><a name="Python_nn65">36.10 Docstring Features</a></H2>