[PATCH 36/36] qom: Include static property API reference in documentation

[Eduardo Habkost]

Add new doc comments and reformat the existing ones,
and include the static-properties.h API reference in
docs/devel/qom.rst.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
 docs/devel/qom.rst            |   6 ++
 include/qom/static-property.h | 154 ++++++++++++++++++++++++++++++++--
 2 files changed, 151 insertions(+), 9 deletions(-)

diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
index 42d0dc4f4d..0989b4e690 100644
--- a/docs/devel/qom.rst
+++ b/docs/devel/qom.rst
@@ -379,3 +379,9 @@ API Reference
 -------------
 
 .. kernel-doc:: include/qom/object.h
+
+
+Static Property API Reference
+-----------------------------
+
+.. kernel-doc:: include/qom/static-property.h
diff --git a/include/qom/static-property.h b/include/qom/static-property.h
index 779918c947..8339700818 100644
--- a/include/qom/static-property.h
+++ b/include/qom/static-property.h
@@ -8,20 +8,31 @@
 #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 static Property
+ *
+ * #Property structs should be always initialized using the
+ * ``DEFINE_PROP`` family of macros.
  */
 struct Property {
+    /* private: */
     const char   *name;
     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;
@@ -110,6 +121,14 @@ extern const PropertyInfo prop_info_link;
 #define DEFINE_PROP_SIGNED_NODEFAULT(_name, _state, _field, _prop, _type) \
     DEFINE_PROP(_name, _state, _field, _prop, _type)
 
+/**
+ * DEFINE_PROP_BIT: Define bit property in uint32_t field
+ * @_name: name of the property
+ * @_state: name of the object state structure type
+ * @_field: name of ``uint32_t`` field in @_state
+ * @_bit: bit offset in @_field
+ * @_defval: default value for bit
+ */
 #define DEFINE_PROP_BIT(_name, _state, _field, _bit, _defval)   \
     DEFINE_PROP(_name, _state, _field, prop_info_bit, uint32_t, \
                 .bitnr       = (_bit),                          \
@@ -124,12 +143,27 @@ extern const PropertyInfo prop_info_link;
 #define DEFINE_PROP_UNSIGNED_NODEFAULT(_name, _state, _field, _prop, _type) \
     DEFINE_PROP(_name, _state, _field, _prop, _type)
 
+/**
+ * DEFINE_PROP_BIT64: Define bit property in uint64_t field
+ * @_name: name of the property
+ * @_state: name of the object state structure type
+ * @_field: name of ``uint64_t`` field in @_state
+ * @_bit: bit offset in @_field
+ * @_defval: default value for bit
+ */
 #define DEFINE_PROP_BIT64(_name, _state, _field, _bit, _defval)   \
     DEFINE_PROP(_name, _state, _field, prop_info_bit64, uint64_t, \
                 .bitnr    = (_bit),                               \
                 .set_default = true,                              \
                 .defval.u  = (bool)_defval)
 
+/**
+ * DEFINE_PROP_BOOL:
+ * @_name: name of the property
+ * @_state: name of the object state structure type
+ * @_field: name of ``bool`` field in @_state
+ * @_defval: default value of property
+ */
 #define DEFINE_PROP_BOOL(_name, _state, _field, _defval)     \
     DEFINE_PROP(_name, _state, _field, prop_info_bool, bool, \
                 .set_default = true,                         \
@@ -142,9 +176,10 @@ 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
+ * @_arrayprop: #PropertyInfo variable defining property type of
+ *              array elements
  * @_arraytype: C type of the array elements
  *
  * Define device properties for a variable-length array _name.  A
@@ -171,36 +206,137 @@ extern const PropertyInfo prop_info_link;
                 .arrayfieldsize = sizeof(_arraytype),          \
                 .arrayoffset = offsetof(_state, _arrayfield))
 
+/**
+ * DEFINE_PROP_LINK: Define object link property
+ * @_name: name of the property
+ * @_state: name of the object state structure type
+ * @_field: name of field in @_state holding the property value
+ * @_type: QOM type name of link target
+ * @_ptr_type: Type of field @_field in struct @_state
+ */
 #define DEFINE_PROP_LINK(_name, _state, _field, _type, _ptr_type)     \
     DEFINE_PROP(_name, _state, _field, prop_info_link, _ptr_type,     \
                 .link_type  = _type)
 
+/**
+ * DEFINE_PROP_UINT8: Define uint8 property
+ * @_n: name of the property
+ * @_s: name of the object state structure type
+ * @_f: name of ``uint8_t`` field in @_s
+ * @_d: default value of property
+ */
 #define DEFINE_PROP_UINT8(_n, _s, _f, _d)                       \
     DEFINE_PROP_UNSIGNED(_n, _s, _f, _d, prop_info_uint8, uint8_t)
+/**
+ * DEFINE_PROP_UINT16: Define uint16 property
+ * @_n: name of the property
+ * @_s: name of the object state structure type
+ * @_f: name of ``uint16_t`` field in @_s
+ * @_d: default value of property
+ */
 #define DEFINE_PROP_UINT16(_n, _s, _f, _d)                      \
     DEFINE_PROP_UNSIGNED(_n, _s, _f, _d, prop_info_uint16, uint16_t)
+/**
+ * DEFINE_PROP_UINT32: Define uint32 property
+ * @_n: name of the property
+ * @_s: name of the object state structure type
+ * @_f: name of ``uint32_t`` field in @_s
+ * @_d: default value of property
+ */
 #define DEFINE_PROP_UINT32(_n, _s, _f, _d)                      \
     DEFINE_PROP_UNSIGNED(_n, _s, _f, _d, prop_info_uint32, uint32_t)
+/**
+ * DEFINE_PROP_INT32: Define int32 property
+ * @_n: name of the property
+ * @_s: name of the object state structure type
+ * @_f: name of ``int32_t`` field in @_s
+ * @_d: default value of property
+ */
 #define DEFINE_PROP_INT32(_n, _s, _f, _d)                      \
     DEFINE_PROP_SIGNED(_n, _s, _f, _d, prop_info_int32, int32_t)
+/**
+ * DEFINE_PROP_UINT64: Define uint64 property
+ * @_n: name of the property
+ * @_s: name of the object state structure type
+ * @_f: name of ``uint64_t`` field in @_s
+ * @_d: default value of property
+ */
 #define DEFINE_PROP_UINT64(_n, _s, _f, _d)                      \
     DEFINE_PROP_UNSIGNED(_n, _s, _f, _d, prop_info_uint64, uint64_t)
+/**
+ * DEFINE_PROP_INT64: Define int64 property
+ * @_n: name of the property
+ * @_s: name of the object state structure type
+ * @_f: name of ``int64_t`` field in @_s
+ * @_d: default value of property
+ */
 #define DEFINE_PROP_INT64(_n, _s, _f, _d)                      \
     DEFINE_PROP_SIGNED(_n, _s, _f, _d, prop_info_int64, int64_t)
+/**
+ * DEFINE_PROP_SIZE: Define uint64 property
+ * @_n: name of the property
+ * @_s: name of the object state structure type
+ * @_f: name of ``uint64_t`` field in @_s
+ * @_d: default value of property
+ */
 #define DEFINE_PROP_SIZE(_n, _s, _f, _d)                       \
     DEFINE_PROP_UNSIGNED(_n, _s, _f, _d, prop_info_size, uint64_t)
+/**
+ * DEFINE_PROP_STRING:
+ * @_n: name of the property
+ * @_s: name of the object state structure type
+ * @_f: name of ``char *`` field in @_state
+ */
 #define DEFINE_PROP_STRING(_n, _s, _f)             \
     DEFINE_PROP(_n, _s, _f, prop_info_string, char*)
+/**
+ * DEFINE_PROP_ON_OFF_AUTO: Define OnOffAuto property
+ * @_n: name of the property
+ * @_s: name of the object state structure type
+ * @_f: name of ``OnOffAuto`` field in @_s
+ * @_d: default value of property
+ */
 #define DEFINE_PROP_ON_OFF_AUTO(_n, _s, _f, _d) \
     DEFINE_PROP_SIGNED(_n, _s, _f, _d, prop_info_on_off_auto, OnOffAuto)
+/**
+ * DEFINE_PROP_SIZE32: Define uint32 property
+ * @_n: name of the property
+ * @_s: name of the object state structure type
+ * @_f: name of ``uint32_t`` field in @_s
+ * @_d: default value of property
+ */
 #define DEFINE_PROP_SIZE32(_n, _s, _f, _d)                       \
     DEFINE_PROP_UNSIGNED(_n, _s, _f, _d, prop_info_size32, uint32_t)
+/**
+ * DEFINE_PROP_UUID: Define UUID property
+ * @_name: name of the property
+ * @_state: name of the object state structure type
+ * @_field: name of field in @_state holding the property value
+ *
+ * The @_f field in struct @_s must be of type ``QemuUUID``.
+ * The default value of the property will be "auto".
+ */
 #define DEFINE_PROP_UUID(_name, _state, _field)                      \
     DEFINE_PROP(_name, _state, _field, prop_info_uuid, QemuUUID,     \
                 .set_default = true)
+/**
+ * DEFINE_PROP_UUID_NODEFAULT: Define UUID property with no default
+ * @_name: name of the property
+ * @_state: name of the object state structure type
+ * @_field: name of field in @_state holding the property value
+ *
+ * The @_f field in struct @_s must be of type ``QemuUUID``.
+ * No default value will be set for the property.
+ */
 #define DEFINE_PROP_UUID_NODEFAULT(_name, _state, _field) \
     DEFINE_PROP(_name, _state, _field, prop_info_uuid, QemuUUID)
 
+/**
+ * DEFINE_PROP_END_OF_LIST: Mark end of property array
+ *
+ * This must be the last entry in #Property arrays when calling
+ * object_class_add_static_props().
+ */
 #define DEFINE_PROP_END_OF_LIST()               \
     {}
 
-- 
2.28.0