Documentation: Add better documentation about object lifetime

doc/efl.rst

@@ -6,6 +6,26 @@
 .. versionadded:: 1.8
 
 
+Object lifetime
+---------------
+
+Eo objects (and any which have the delete() method) get their reference count
+internally increased by one at object creation. This means that these objects
+will not get freed when you release all references to them in your application.
+You must call the objects' delete() method to decrease the internal reference
+count. This will usually also trigger some kind of action to destroy
+the object gracefully, i.e. hiding the graphical object etc, and will set the
+C object pointer to NULL, which will prevent you from calling methods on the
+object.
+
+If you can't keep track of when your application calls the delete method, you
+can check that your object is still valid with either the is_deleted() method,
+or with a non-zero check::
+
+    if eo_obj:
+        print(repr(eo_obj))
+
+
 Logging
 -------
 

efl/eo/efl.eo.pyx

@@ -283,11 +283,17 @@ cdef class Eo(object):
         return EoIterator.create(efl_children_iterator_new(self.obj))
 
     def delete(self):
-        """Delete the object and free internal resources.
+        """Decrease internal reference count and delete the object gracefully
 
-        .. note:: This will not delete the python object, but only the internal
-            C one. The python object will be automatically deleted by the
-            garbage collector when there are no more reference to it.
+        .. note:: Reference count will be decreased at the del callback, not
+            instantly when calling this. Same for setting the internal
+            object pointer to NULL and freeing any internal resources.
+
+        .. note:: This will not automatically free the Python object, only
+            the wrapped C object. This will prevent you from calling methods
+            other than :meth:`is_deleted` and accessing properties on the
+            object. The Python object will be automatically freed by Python
+            when there are no more references to it.
 
         """
         efl_del(self.obj)