[PATCH v3 03/30] docstring: Fix generated documentation of virConnectListAllNodeDeviceFlags

[Peter Krempa]

On Wed, Apr 20, 2022 at 21:07:52 +0200, Victor Toso wrote:
> scripts/apibuild.py does not handle well enum's with comments
> between values.  The outcome depends on whether the enum value has
> its own docstring or not and if there is spaces between the enum
> values or not.
> 
> Either way, virConnectListAllNodeDeviceFlags documentation is
> explicit that this enum is about filtering node devices. We can move
> the information that it is either by "capability" or "active" state
> to the block of comment above.
> 
> Using git diff --word-diff to show the fixed ouput xml (redacted).
> 
>   <enum name='VIR_CONNECT_LIST_NODE_DEVICES_ACTIVE' ... [-info='Inactive-]{+info='Active+} devices'/>
>   <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_AP_CARD' ... [-info='vDPA-]{+info='s390 AP Card+} device'/>
>   <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_AP_MATRIX' ... [-Queue'/>-]{+Matrix'/>+}
>   <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_AP_QUEUE' ... [-Card device'/>-]{+Queue'/>+}
>   <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_CCW_DEV' ... [-info='Mediated-]{+info='CCW+} device'/>
>   <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_CSS_DEV' ... [-info='CCW-]{+info='CSS+} device'/>
>   <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_DRM' ... [-info='Capable of scsi_generic'/>-]{+info='DRM device'/>+}
>   <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_FC_HOST' ... [-info='Storage device'/>-]{+info='FC Host Bus Adapter'/>+}
>   <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_MDEV' ... [-info='Capable of mediated devices'/>-]{+info='Mediated device'/>+}
>   <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_MDEV_TYPES' ... [-info='DRM device'/>-]{+info='Capable of mediated devices'/>+}
>   <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_NET' ... [-info='USB interface'/>-]{+info='Network device'/>+}
>   <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_PCI_DEV' ... [-info='System capability'/>-]{+info='PCI device'/>+}
>   <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_SCSI' ... [-Target'/>-]{+device'/>+}
>   <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_SCSI_GENERIC' ... [-vport'/>-]{+scsi_generic'/>+}
>   <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_SCSI_HOST' ... [-info='Network device'/>-]{+info='SCSI Host Bus Adapter'/>+}
>   <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_SCSI_TARGET' ... [-Host Bus Adapter'/>-]{+Target'/>+}
>   <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_STORAGE' ... [-info='SCSI-]{+info='Storage+} device'/>
>   <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_SYSTEM' ... [-info='filter the devices by cap type'/>-]{+info='System capability'/>+}
>   <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_USB_DEV' ... [-info='PCI-]{+info='USB+} device'/>
>   <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_USB_INTERFACE' ... [-device'/>-]{+interface'/>+}
>   <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_VDPA' ... [-info='CSS-]{+info='vDPA+} device'/>
>   <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_VPD' ... [-info='s390 AP Matrix'/>-]{+info='Device with VPD'/>+}
>   <enum name='VIR_CONNECT_LIST_NODE_DEVICES_CAP_VPORTS' ... [-info='FC Host Bus Adapter'/>-]{+info='Capable of vport'/>+}
>   <enum name='VIR_CONNECT_LIST_NODE_DEVICES_INACTIVE' ... [-info='Device with VPD filter the devices by active state'/>-]{+info='Inactive devices'/>+}
> 
> Signed-off-by: Victor Toso <victortoso at redhat.com>
> ---
>  include/libvirt/libvirt-nodedev.h | 5 ++---
>  1 file changed, 2 insertions(+), 3 deletions(-)
> 
> diff --git a/include/libvirt/libvirt-nodedev.h b/include/libvirt/libvirt-nodedev.h
> index 0c01d51aab..8efcd7f506 100644
> --- a/include/libvirt/libvirt-nodedev.h
> +++ b/include/libvirt/libvirt-nodedev.h
> @@ -60,9 +60,9 @@ int                     virNodeListDevices      (virConnectPtr conn,
>  /*
>   * virConnectListAllNodeDevices:
>   *
> - * Flags used to filter the returned node devices.  */
> + * Flags used to filter either by capability or active state, the
> + * returned node devices. */
>  typedef enum {
> -    /* filter the devices by cap type */
>      VIR_CONNECT_LIST_NODE_DEVICES_CAP_SYSTEM        = 1 << 0,  /* System capability */
>      VIR_CONNECT_LIST_NODE_DEVICES_CAP_PCI_DEV       = 1 << 1,  /* PCI device */
>      VIR_CONNECT_LIST_NODE_DEVICES_CAP_USB_DEV       = 1 << 2,  /* USB device */
> @@ -86,7 +86,6 @@ typedef enum {
>      VIR_CONNECT_LIST_NODE_DEVICES_CAP_AP_MATRIX     = 1 << 20, /* s390 AP Matrix */
>      VIR_CONNECT_LIST_NODE_DEVICES_CAP_VPD           = 1 << 21, /* Device with VPD */
>  
> -    /* filter the devices by active state */
>      VIR_CONNECT_LIST_NODE_DEVICES_INACTIVE          = 1 << 30, /* Inactive devices */
>      VIR_CONNECT_LIST_NODE_DEVICES_ACTIVE            = 1U << 31, /* Active devices */
>  } virConnectListAllNodeDeviceFlags;

I'd simply just drop the comments.

Reviewed-by: Peter Krempa <pkrempa at redhat.com>

I'll push this one after I'm done with the review.