[PATCH v3 47/53] qom: Include static property API reference in documentation

[Eduardo Habkost]

Include the static-properties.h API reference in
docs/devel/qom.rst.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
Changes v2 -> v3:
* Redone patch after changes in previous patches in the series
* Split into separate patches.  This one only adds the file to
  qom.rst and Property/PropertyInfo doc comments.  Another patch
  will add the documentation for DEFINE_PROP_* and PROP_*.

Changes v1 -> v2:
* Redone patch after changes in previous patches in the series
---
Cc: Paolo Bonzini <pbonzini@redhat.com>
Cc: "Daniel P. Berrangé" <berrange@redhat.com>
Cc: Eduardo Habkost <ehabkost@redhat.com>
Cc: qemu-devel@nongnu.org
---
 docs/devel/qom.rst           | 17 +++++++++++++-
 include/qom/field-property.h | 45 ++++++++++++++++++++++++++++++------
 include/qom/property-types.h |  2 +-
 3 files changed, 55 insertions(+), 9 deletions(-)

diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
index 42d0dc4f4d..9e43aa46f2 100644
--- a/docs/devel/qom.rst
+++ b/docs/devel/qom.rst
@@ -376,6 +376,21 @@ the OBJECT_DEFINE_ABSTRACT_TYPE() macro can be used 
instead:
 
 
 API Reference
--------------
+=============
+
+Core QOM API Reference
+----------------------
 
 .. kernel-doc:: include/qom/object.h
+
+
+Field Property API Reference
+----------------------------
+
+.. kernel-doc:: include/qom/field-property.h
+
+
+Property Types Reference
+------------------------
+
+.. kernel-doc:: include/qom/property-types.h
diff --git a/include/qom/field-property.h b/include/qom/field-property.h
index 91e7a43165..419e5eef75 100644
--- a/include/qom/field-property.h
+++ b/include/qom/field-property.h
@@ -8,15 +8,14 @@
 #include "qapi/util.h"
 
 /**
- * Property:
- * @set_default: true if the default value should be set from @defval,
- *    in which case @info->set_default_value must not be NULL
- *    (if false then no default value is set by the property system
- *     and the field retains whatever value it was given by instance_init).
- * @defval: default value for the property. This is used only if @set_default
- *     is true.
+ * struct Property: definition of a field property
+ *
+ * Field properties are used to read and write fields in object
+ * instance structs.  Field properties are defined using
+ * ``PROP_<type>`` or ``DEFINE_PROP_<type>``.
  */
 struct Property {
+    /* private: */
     /**
      * @name_template: Property name template
      *
@@ -28,27 +27,59 @@ struct Property {
     const PropertyInfo *info;
     ptrdiff_t    offset;
     uint8_t      bitnr;
+    /**
+     * @set_default: true if the default value should be set from @defval,
+     *    in which case @info->set_default_value must not be NULL
+     *    (if false then no default value is set by the property system
+     *     and the field retains whatever value it was given by instance_init).
+     */
     bool         set_default;
+    /**
+     * @defval: default value for the property. This is used only if 
@set_default
+     *     is true.
+     */
     union {
         int64_t i;
         uint64_t u;
     } defval;
+    /* private: */
     int          arrayoffset;
     const PropertyInfo *arrayinfo;
     int          arrayfieldsize;
     const char   *link_type;
 };
 
+/**
+ * struct PropertyInfo: information on a specific QOM property type
+ */
 struct PropertyInfo {
+    /** @name: property type name */
     const char *name;
+    /** @description: Description for help text */
     const char *description;
+    /** @enum_table: Used by field_prop_get_enum() and field_prop_set_enum() */
     const QEnumLookup *enum_table;
+    /** @print: String formatting function, for the human monitor */
     int (*print)(Object *obj, Property *prop, char *dest, size_t len);
+    /** @set_default_value: Callback for initializing the default value */
     void (*set_default_value)(ObjectProperty *op, const Property *prop);
+    /** @create: Optional callback for creation of property */
     ObjectProperty *(*create)(ObjectClass *oc, const char *name,
                               Property *prop);
+    /**
+     * @get: Property getter.  The opaque parameter will point to
+     *        the &Property struct for the property.
+     */
     ObjectPropertyAccessor *get;
+    /**
+     * @set: Property setter.  The opaque parameter will point to
+     *        the &Property struct for the property.
+     */
     ObjectPropertyAccessor *set;
+    /**
+     * @release: Optional release function, called when the object
+     * is destroyed
+     */
     ObjectPropertyRelease *release;
 };
 
diff --git a/include/qom/property-types.h b/include/qom/property-types.h
index 0aff0d9474..46c82da4e3 100644
--- a/include/qom/property-types.h
+++ b/include/qom/property-types.h
@@ -71,7 +71,7 @@ extern const PropertyInfo prop_info_link;
  * @_name: name of the array
  * @_state: name of the device state structure type
  * @_field: uint32_t field in @_state to hold the array length
- * @_arrayfield: field in @_state (of type '@_arraytype *') which
+ * @_arrayfield: field in @_state (of type ``_arraytype *``) which
  *               will point to the array
  * @_arrayprop: PropertyInfo defining what property the array elements have
  * @_arraytype: C type of the array elements
-- 
2.28.0