qom: Use command line syntax for default values in help

Commit Message

Akihiko Odaki Feb. 7, 2025, 5:53 a.m. UTC

object_property_help() uses the conventional command line syntax instead
of the JSON syntax. In particular,
- Key-value pairs are written in the command line syntax.
- bool description passed to the function says on/off instead of
  true/false.

However, there is one exception: default values are formatted into JSON.
While the command line and JSON syntaxes are consistent in many cases,
there are two types where they disagree:

string: The command line syntax omits quotes while JSON requires them.

bool: JSON only accepts true/false for bool but the command line syntax
      accepts on/off too, and on/off are also more popular than
      true/false. For example, the docs directory has 2045 "on"
      occurances while it has only 194 "true" occurances.
      on/off are also accepted by OnOffAuto so users do not have to
      remember the type is bool or OnOffAuto to use the values.

Omit quotes for strings and use on/off for bools when formatting
default values for better consistency.

Signed-off-by: Akihiko Odaki <[e-mail]>
---
 qom/object_interfaces.c | 24 +++++++++++++++++++++---
 1 file changed, 21 insertions(+), 3 deletions(-)


---
base-commit: 7433709a147706ad7d1956b15669279933d0f82b
change-id: 20250207-bool-967267fd0a25

Best regards,

Comments

Markus Armbruster Feb. 14, 2025, 3:18 p.m. UTC | #1

Akihiko Odaki <[e-mail]> writes:

> object_property_help() uses the conventional command line syntax instead
> of the JSON syntax. In particular,
> - Key-value pairs are written in the command line syntax.
> - bool description passed to the function says on/off instead of
>   true/false.
>
> However, there is one exception: default values are formatted into JSON.
> While the command line and JSON syntaxes are consistent in many cases,
> there are two types where they disagree:
>
> string: The command line syntax omits quotes while JSON requires them.
>
> bool: JSON only accepts true/false for bool but the command line syntax
>       accepts on/off too, and on/off are also more popular than
>       true/false. For example, the docs directory has 2045 "on"
>       occurances while it has only 194 "true" occurances.
>       on/off are also accepted by OnOffAuto so users do not have to
>       remember the type is bool or OnOffAuto to use the values.
>
> Omit quotes for strings and use on/off for bools when formatting
> default values for better consistency.
>
> Signed-off-by: Akihiko Odaki <[e-mail]>

Acked-by: Markus Armbruster <[e-mail]>

Paolo Bonzini Feb. 14, 2025, 3:47 p.m. UTC | #2

Queued, thanks.

Paolo

Patch

diff --git a/qom/object_interfaces.c b/qom/object_interfaces.c
index 1a6f29c053e45bf5da5252f6ac1dfa4e85627f9f..f2450f8099c366864b56940e19c6a4bcc0d5e3a9 100644
--- a/qom/object_interfaces.c
+++ b/qom/object_interfaces.c
@@ -4,9 +4,11 @@ 
 #include "qapi/error.h"
 #include "qapi/qapi-visit-qom.h"
 #include "qapi/qmp/qobject.h"
+#include "qapi/qmp/qbool.h"
 #include "qapi/qmp/qdict.h"
 #include "qapi/qmp/qerror.h"
 #include "qapi/qmp/qjson.h"
+#include "qapi/qmp/qstring.h"
 #include "qapi/qobject-input-visitor.h"
 #include "qapi/qobject-output-visitor.h"
 #include "qom/object_interfaces.h"
@@ -177,9 +179,25 @@  char *object_property_help(const char *name, const char *type,
         g_string_append(str, description);
     }
     if (defval) {
-        g_autofree char *def_json = g_string_free(qobject_to_json(defval),
-                                                  false);
-        g_string_append_printf(str, " (default: %s)", def_json);
+        g_autofree char *def_json = NULL;
+        const char *def;
+
+        switch (qobject_type(defval)) {
+        case QTYPE_QSTRING:
+            def = qstring_get_str(qobject_to(QString, defval));
+            break;
+
+        case QTYPE_QBOOL:
+            def = qbool_get_bool(qobject_to(QBool, defval)) ? "on" : "off";
+            break;
+
+        default:
+            def_json = g_string_free(qobject_to_json(defval), false);
+            def = def_json;
+            break;
+        }
+
+        g_string_append_printf(str, " (default: %s)", def);
     }
 
     return g_string_free(str, false);