[PATCH 15/18] qapi: add cross-references to ui.json

John Snow posted 18 patches 8 months ago
Maintainers: Eric Blake <eblake@redhat.com>, Markus Armbruster <armbru@redhat.com>, "Michael S. Tsirkin" <mst@redhat.com>, Igor Mammedov <imammedo@redhat.com>, Ani Sinha <anisinha@redhat.com>, "Daniel P. Berrangé" <berrange@redhat.com>, Kevin Wolf <kwolf@redhat.com>, Hanna Reitz <hreitz@redhat.com>, "Marc-André Lureau" <marcandre.lureau@redhat.com>, John Snow <jsnow@redhat.com>, Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>, Eduardo Habkost <eduardo@habkost.net>, Marcel Apfelbaum <marcel.apfelbaum@gmail.com>, "Philippe Mathieu-Daudé" <philmd@linaro.org>, Yanan Wang <wangyanan55@huawei.com>, Zhao Liu <zhao1.liu@intel.com>, Peter Xu <peterx@redhat.com>, Fabiano Rosas <farosas@suse.de>, Jason Wang <jasowang@redhat.com>, Paolo Bonzini <pbonzini@redhat.com>, "Alex Bennée" <alex.bennee@linaro.org>, Lukas Straub <lukasstraub2@web.de>
There is a newer version of this series
[PATCH 15/18] qapi: add cross-references to ui.json
Posted by John Snow 8 months ago
Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/ui.json | 34 +++++++++++++++++-----------------
 1 file changed, 17 insertions(+), 17 deletions(-)

diff --git a/qapi/ui.json b/qapi/ui.json
index 7136c985c38..5bc54403cc2 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -39,7 +39,7 @@
 ##
 # @SetPasswordOptions:
 #
-# Options for set_password.
+# Options for `set_password`.
 #
 # @protocol:
 #     - 'vnc' to modify the VNC server password
@@ -63,7 +63,7 @@
 ##
 # @SetPasswordOptionsVnc:
 #
-# Options for set_password specific to the VNC protocol.
+# Options for `set_password` specific to the VNC protocol.
 #
 # @display: The id of the display where the password should be
 #     changed.  Defaults to the first.
@@ -94,7 +94,7 @@
 ##
 # @ExpirePasswordOptions:
 #
-# General options for expire_password.
+# General options for `expire_password`.
 #
 # @protocol:
 #     - 'vnc' to modify the VNC server expiration
@@ -124,7 +124,7 @@
 ##
 # @ExpirePasswordOptionsVnc:
 #
-# Options for expire_password specific to the VNC protocol.
+# Options for `expire_password` specific to the VNC protocol.
 #
 # @display: The id of the display where the expiration should be
 #     changed.  Defaults to the first.
@@ -183,7 +183,7 @@
 #     the head can only be specified in conjunction with the device
 #     ID.  (Since 2.12)
 #
-# @format: image format for screendump.  (default: ppm) (Since 7.1)
+# @format: image format for `screendump`.  (default: ppm) (Since 7.1)
 #
 # Since: 0.14
 #
@@ -310,7 +310,7 @@
 #     unknown if spice server doesn't provide this information.
 #     (since: 1.1)
 #
-# @channels: a list of @SpiceChannel for each active spice channel
+# @channels: a list of `SpiceChannel` for each active spice channel
 #
 # Since: 0.14
 ##
@@ -559,7 +559,7 @@
 #     - 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL
 #       auth
 #
-# @clients: a list of @VncClientInfo of all currently connected
+# @clients: a list of `VncClientInfo` of all currently connected
 #     clients
 #
 # Since: 0.14
@@ -622,12 +622,12 @@
 #
 # @id: vnc server name.
 #
-# @server: A list of @VncBasincInfo describing all listening sockets.
+# @server: A list of `VncBasicInfo` describing all listening sockets.
 #     The list can be empty (in case the vnc server is disabled).  It
 #     also may have multiple entries: normal + websocket, possibly
 #     also ipv4 + ipv6 in the future.
 #
-# @clients: A list of @VncClientInfo of all currently connected
+# @clients: A list of `VncClientInfo` of all currently connected
 #     clients.  The list can be empty, for obvious reasons.
 #
 # @auth: The current authentication type used by the non-websockets
@@ -846,7 +846,7 @@
 #
 # An enumeration of key name.
 #
-# This is used by the @send-key command.
+# This is used by the `send-key` command.
 #
 # @unmapped: since 2.0
 #
@@ -1017,10 +1017,10 @@
 #
 # Send keys to guest.
 #
-# @keys: An array of @KeyValue elements.  All @KeyValues in this array
-#     are simultaneously sent to the guest.  A @KeyValue.number value
-#     is sent directly to the guest, while @KeyValue.qcode must be a
-#     valid @QKeyCode value
+# @keys: An array of `KeyValue` elements.  All @KeyValues in this array
+#     are simultaneously sent to the guest.  A `KeyValue`.number value
+#     is sent directly to the guest, while `KeyValue`.qcode must be a
+#     valid `QKeyCode` value
 #
 # @hold-time: time to delay key up events, milliseconds.  Defaults to
 #     100
@@ -1257,7 +1257,7 @@
 # @head: head to send event(s) to, in case the display device supports
 #     multiple scanouts.
 #
-# @events: List of InputEvent union.
+# @events: List of `InputEvent` union.
 #
 # Since: 2.6
 #
@@ -1361,7 +1361,7 @@
 #     first available node on the host.
 #
 # @p2p: Whether to use peer-to-peer connections (accepted through
-#     @add_client).
+#     `add_client`).
 #
 # @audiodev: Use the specified DBus audiodev to export audio.
 #
@@ -1520,7 +1520,7 @@
 #
 # Display (user interface) options.
 #
-# @type: Which DisplayType QEMU should use.
+# @type: Which `DisplayType` QEMU should use.
 #
 # @full-screen: Start user interface in fullscreen mode
 #     (default: off).
-- 
2.48.1
Re: [PATCH 15/18] qapi: add cross-references to ui.json
Posted by Markus Armbruster 7 months, 1 week ago
John Snow <jsnow@redhat.com> writes:

> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  qapi/ui.json | 34 +++++++++++++++++-----------------
>  1 file changed, 17 insertions(+), 17 deletions(-)
>
> diff --git a/qapi/ui.json b/qapi/ui.json
> index 7136c985c38..5bc54403cc2 100644
> --- a/qapi/ui.json
> +++ b/qapi/ui.json
> @@ -39,7 +39,7 @@
>  ##
>  # @SetPasswordOptions:
>  #
> -# Options for set_password.
> +# Options for `set_password`.
>  #
>  # @protocol:
>  #     - 'vnc' to modify the VNC server password
> @@ -63,7 +63,7 @@
>  ##
>  # @SetPasswordOptionsVnc:
>  #
> -# Options for set_password specific to the VNC protocol.
> +# Options for `set_password` specific to the VNC protocol.
>  #
>  # @display: The id of the display where the password should be
>  #     changed.  Defaults to the first.
> @@ -94,7 +94,7 @@
>  ##
>  # @ExpirePasswordOptions:
>  #
> -# General options for expire_password.
> +# General options for `expire_password`.
>  #
>  # @protocol:
>  #     - 'vnc' to modify the VNC server expiration
> @@ -124,7 +124,7 @@
>  ##
>  # @ExpirePasswordOptionsVnc:
>  #
> -# Options for expire_password specific to the VNC protocol.
> +# Options for `expire_password` specific to the VNC protocol.
>  #
>  # @display: The id of the display where the expiration should be
>  #     changed.  Defaults to the first.
> @@ -183,7 +183,7 @@
>  #     the head can only be specified in conjunction with the device
>  #     ID.  (Since 2.12)
>  #
> -# @format: image format for screendump.  (default: ppm) (Since 7.1)
> +# @format: image format for `screendump`.  (default: ppm) (Since 7.1)

This is a link from a command argument back to the command.  Meh.  The
real issue is of course that the argument description is sub-par: "for
screendump" is entirely redundant.  Not for this patch to address.

Similarly crappy text descriptions may well exist elsewhere.  If we care
to clean them up, perhaps we can use "link to definition within the same
definition" to find them.

>  #
>  # Since: 0.14
>  #

[...]