qom: Extend documentation on QOM method concepts

Add a documentation section "Methods" and discuss among others how to
handle overriding virtual methods.

Clarify DeviceClass::realize documentation and refer to the above.

Signed-off-by: Andreas Färber <afaerber@suse.de>
Signed-off-by: Anthony Liguori <aliguori@us.ibm.com>

1 files changed, 10 insertions, 4 deletions

diff --git a/hw/qdev-core.h b/hw/qdev-core.h
index 3d75ae2e3a..731aadd677 100644
--- a/hw/qdev-core.h
+++ b/hw/qdev-core.h
@@ -60,14 +60,20 @@ struct VMStateDescription;
  * The @init callback is considered private to a particular bus implementation
  * (immediate abstract child types of TYPE_DEVICE). Derived leaf types set an
  * "init" callback on their parent class instead.
+ *
  * Any type may override the @realize and/or @unrealize callbacks but needs
- * to call (and thus save) the parent type's implementation if so desired.
- * Usually this means storing the previous value of, e.g., @realized inside
- * the type's class structure and overwriting it with a function that first
- * invokes the stored callback, then performs any additional steps.
+ * to call the parent type's implementation if keeping their functionality
+ * is desired. Refer to QOM documentation for further discussion and examples.
+ *
+ * <note>
+ *   <para>
  * If a type derived directly from TYPE_DEVICE implements @realize, it does
  * not need to implement @init and therefore does not need to store and call
  * #DeviceClass' default @realize callback.
+ * For other types consult the documentation and implementation of the
+ * respective parent types.
+ *   </para>
+ * </note>
  */
 typedef struct DeviceClass {
     /*< private >*/