virobject: Improve documentation

I had to inspect the code to learn whether a final virObjectUnref()
calls ALL dispose callbacks in child-to-parent order (akin to C++
destructors), or whether I manually had to call a parent-class dispose
when writing a child class dispose method.  The answer is the
former. (Thankfully, since VIR_FREE wipes out pointers for safety,
even if I had guessed wrong, I probably would not have tripped over a
double-free fault when the parent dispose ran for the second time).  I
also had to read the code to learn if a dispose method was even
mandatory (it is not, although getting NULL through VIR_CLASS_NEW
requires a macro).  While at it, the VIR_CLASS_NEW macro requires that
the virObject component at offset 0 be reached through the name
'parent', not 'object'.

Signed-off-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>

src/util/virobject.c

@@ -147,10 +147,11 @@ virClassForObjectRWLockable(void)
  *
  * Register a new object class with @name. The @objectSize
  * should give the total size of the object struct, which
- * is expected to have a 'virObject object;' field as its
- * first member. When the last reference on the object is
- * released, the @dispose callback will be invoked to free
- * memory of the object fields
+ * is expected to have a 'virObject parent;' field as (or
+ * contained in) its first member. When the last reference
+ * on the object is released, the @dispose callback will be
+ * invoked to free memory of the local object fields, as
+ * well as the dispose callbacks of the parent classes.
  *
  * Returns a new class instance
  */
@@ -326,8 +327,9 @@ virObjectRWLockableDispose(void *anyobj)
  * @anyobj: any instance of virObjectPtr
  *
  * Decrement the reference count on @anyobj and if
- * it hits zero, runs the "dispose" callback associated
- * with the object class and frees @anyobj.
+ * it hits zero, runs the "dispose" callbacks associated
+ * with the object class and its parents before freeing
+ * @anyobj.
  *
  * Returns true if the remaining reference count is
  * non-zero, false if the object was disposed of

src/util/virobject.h

@@ -75,6 +75,11 @@ virClassPtr virClassForObjectRWLockable(void);
 #  define VIR_PARENT_REQUIRED ATTRIBUTE_NONNULL(1)
 # endif
 
+/* Assign the class description nameClass to represent struct @name
+ * (which must have an object-based 'parent' member at offset 0), and
+ * with parent class @prnt. nameDispose must exist as either a
+ * function or as a macro defined to NULL.
+ */
 # define VIR_CLASS_NEW(name, prnt) \
     verify_expr(offsetof(name, parent) == 0, \
       (name##Class = virClassNew(prnt, #name, sizeof(name), name##Dispose)))