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

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(a)redhat.com&gt; --- 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;