| Message ID | 20240205074709.3613229-10-armbru@redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | qapi: Require member documentation (with loophole) | expand |
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
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.
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 ##
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(-)