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

[Victor Toso]

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;
-- 
2.35.1