Add missing return member documentation of guest-get-disks,
guest-get-devices, guest-get-diskstats, and guest-get-cpustats.

The NVMe SMART information returned by guest-getdisks remains
undocumented.  Add a TODO there.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qga/qapi-schema.json | 24 ++++++++++++++----------
 1 file changed, 14 insertions(+), 10 deletions(-)

diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
index f3d168d542..b8efe31897 100644
--- a/qga/qapi-schema.json
+++ b/qga/qapi-schema.json
@@ -36,12 +36,6 @@
         'guest-sync-delimited' ],
     # Types and commands with undocumented members:
     'documentation-exceptions': [
-        'GuestCpuStats',
-        'GuestCpuStatsType',
-        'GuestDeviceId',
-        'GuestDeviceType',
-        'GuestDiskSmart',
-        'GuestDiskStatsInfo',
         'GuestNVMeSmart' ] } }
 
 ##
@@ -944,6 +938,8 @@
 # NVMe smart information, based on NVMe specification, section
 # <SMART / Health Information (Log Identifier 02h)>
 #
+# TODO: document members briefly
+#
 # Since: 7.1
 ##
 { 'struct': 'GuestNVMeSmart',
@@ -978,7 +974,7 @@
 #
 # Disk type related smart information.
 #
-# - @nvme: NVMe disk smart
+# @type: disk bus type
 #
 # Since: 7.1
 ##
@@ -1499,6 +1495,8 @@
 
 ##
 # @GuestDeviceType:
+#
+# @pci: PCI device
 ##
 { 'enum': 'GuestDeviceType',
   'data': [ 'pci' ] }
@@ -1518,7 +1516,9 @@
 ##
 # @GuestDeviceId:
 #
-# Id of the device - @pci: PCI ID, since: 5.2
+# Id of the device
+#
+# @type: device type
 #
 # Since: 5.2
 ##
@@ -1700,6 +1700,8 @@
 # @major: major device number of disk
 #
 # @minor: minor device number of disk
+#
+# @stats: I/O statistics
 ##
 { 'struct': 'GuestDiskStatsInfo',
   'data': {'name': 'str',
@@ -1723,7 +1725,9 @@
 ##
 # @GuestCpuStatsType:
 #
-# An enumeration of OS type
+# Guest operating systems supporting CPU statistics
+#
+# @linux: Linux
 #
 # Since: 7.1
 ##
@@ -1780,7 +1784,7 @@
 #
 # Get statistics of each CPU in millisecond.
 #
-# - @linux: Linux style CPU statistics
+# @type: guest operating system
 #
 # Since: 7.1
 ##
-- 
2.43.0

On Mon, Feb 05, 2024 at 08:47:03AM +0100, Markus Armbruster wrote:
> Add missing return member documentation of guest-get-disks,
> guest-get-devices, guest-get-diskstats, and guest-get-cpustats.
> 
> The NVMe SMART information returned by guest-getdisks remains
> undocumented.  Add a TODO there.
> 
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  qga/qapi-schema.json | 24 ++++++++++++++----------
>  1 file changed, 14 insertions(+), 10 deletions(-)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

> @@ -978,7 +974,7 @@
>  #
>  # Disk type related smart information.
>  #
> -# - @nvme: NVMe disk smart
> +# @type: disk bus type
>  #
>  # Since: 7.1
>  ##

Fun, so not only were the fields that exist not documented,
but we've documented fields which don't exist.


> @@ -1780,7 +1784,7 @@
>  #
>  # Get statistics of each CPU in millisecond.
>  #
> -# - @linux: Linux style CPU statistics
> +# @type: guest operating system
>  #
>  # Since: 7.1
>  ##

And more things which don't exist !


With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Daniel P. Berrangé <berrange@redhat.com> writes:

> On Mon, Feb 05, 2024 at 08:47:03AM +0100, Markus Armbruster wrote:
>> Add missing return member documentation of guest-get-disks,
>> guest-get-devices, guest-get-diskstats, and guest-get-cpustats.
>> 
>> The NVMe SMART information returned by guest-getdisks remains
>> undocumented.  Add a TODO there.
>> 
>> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>> ---
>>  qga/qapi-schema.json | 24 ++++++++++++++----------
>>  1 file changed, 14 insertions(+), 10 deletions(-)
>
> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
>
>> @@ -978,7 +974,7 @@
>>  #
>>  # Disk type related smart information.
>>  #
>> -# - @nvme: NVMe disk smart
>> +# @type: disk bus type
>>  #
>>  # Since: 7.1
>>  ##
>
> Fun, so not only were the fields that exist not documented,
> but we've documented fields which don't exist.

I think the @nvme line tried to document the branch.  Not useful; the
doc generator takes care of that:

    GuestDiskSmart (Object)
    -----------------------

    Disk type related smart information.

    * nvme: NVMe disk smart

    Members
    ~~~~~~~

    "type": "GuestDiskBusType"
        Not documented

--> The members of "GuestNVMeSmart" when "type" is "nvme"

>> @@ -1780,7 +1784,7 @@
>>  #
>>  # Get statistics of each CPU in millisecond.
>>  #
>> -# - @linux: Linux style CPU statistics
>> +# @type: guest operating system
>>  #
>>  # Since: 7.1
>>  ##
>
> And more things which don't exist !

Likewise.