qom: Add description field in ObjectProperty struct

The descriptions can serve as documentation in the code,
and they can be used to provide better help.

Copy property descriptions when copying alias properties.

Cc: Markus Armbruster <[email protected]>
Signed-off-by: Gonglei <[email protected]>
Reviewed-by: Paolo Bonzini <[email protected]>
Reviewed-by: Michael S. Tsirkin <[email protected]>
Signed-off-by: Andreas Färber <[email protected]>

diff --git a/include/qom/object.h b/include/qom/object.h
index 8a05a81a991d30b41f55d87f4a1241f09f799df1..89c3092967e152a88e458b46b7ab3d4ad35dbfb9 100644 (file)
--- a/include/qom/object.h
+++ b/include/qom/object.h
@@ -338,6 +338,7 @@ typedef struct ObjectProperty
 {
     gchar *name;
     gchar *type;
+    gchar *description;
     ObjectPropertyAccessor *get;
     ObjectPropertyAccessor *set;
     ObjectPropertyResolve *resolve;
@@ -1274,6 +1275,19 @@ void object_property_add_alias(Object *obj, const char *name,
                                Object *target_obj, const char *target_name,
                                Error **errp);
 
+/**
+ * object_property_set_description:
+ * @obj: the object owning the property
+ * @name: the name of the property
+ * @description: the description of the property on the object
+ * @errp: if an error occurs, a pointer to an area to store the error
+ *
+ * Set an object property's description.
+ *
+ */
+void object_property_set_description(Object *obj, const char *name,
+                                     const char *description, Error **errp);
+
 /**
  * object_child_foreach:
  * @obj: the object whose children will be navigated

diff --git a/qom/object.c b/qom/object.c
index 575291f10958e8356460cd1fa5f13d9cc9704ffb..a751367e618e3b8e8dfa0d4a72d8c08e58826d11 100644 (file)
--- a/qom/object.c
+++ b/qom/object.c
@@ -369,6 +369,7 @@ static void object_property_del_all(Object *obj)
 
         g_free(prop->name);
         g_free(prop->type);
+        g_free(prop->description);
         g_free(prop);
     }
 }
@@ -803,6 +804,7 @@ void object_property_del(Object *obj, const char *name, Error **errp)
 
     g_free(prop->name);
     g_free(prop->type);
+    g_free(prop->description);
     g_free(prop);
 }
 
@@ -1672,10 +1674,28 @@ void object_property_add_alias(Object *obj, const char *name,
     }
     op->resolve = property_resolve_alias;
 
+    object_property_set_description(obj, name,
+                                    target_prop->description,
+                                    &error_abort);
+
 out:
     g_free(prop_type);
 }
 
+void object_property_set_description(Object *obj, const char *name,
+                                     const char *description, Error **errp)
+{
+    ObjectProperty *op;
+
+    op = object_property_find(obj, name, errp);
+    if (!op) {
+        return;
+    }
+
+    g_free(op->description);
+    op->description = g_strdup(description);
+}
+
 static void object_instance_init(Object *obj)
 {
     object_property_add_str(obj, "type", qdev_get_type, NULL, NULL);