From 14bf7270aabcc7af519284b4023f6ad9b7b35749 Mon Sep 17 00:00:00 2001
From: Matthias Bolte <matthias.bolte@googlemail.com>
Date: Wed, 30 Sep 2009 13:41:28 +0200
Subject: [PATCH] Fix apibuild.py warnings

Function comments for virStreamEvent{Add,Update,Remove}Callback() are
missing a trailing ':'. Therefore apibuild.py fails to parse the comment
and warns about the missing ':'.

* docs/libvirt-api.xml, docs/libvirt-refs.xml: updated by apibuild.py
* src/libvirt.c: add missing ':' in function comments
---
 docs/libvirt-api.xml  | 36 +++++++++++++---------
 docs/libvirt-refs.xml | 72 +++++++++++++++++++++++++++++++++++++++++++
 src/libvirt.c         |  6 ++--
 3 files changed, 96 insertions(+), 18 deletions(-)

diff --git a/docs/libvirt-api.xml b/docs/libvirt-api.xml
index 5981c0ed68..795701c3ed 100644
--- a/docs/libvirt-api.xml
+++ b/docs/libvirt-api.xml
@@ -47,7 +47,6 @@
      <exports symbol='VIR_MIGRATE_LIVE' type='enum'/>
      <exports symbol='VIR_DOMAIN_EVENT_STOPPED_DESTROYED' type='enum'/>
      <exports symbol='VIR_DOMAIN_EVENT_DEFINED_ADDED' type='enum'/>
-     <exports symbol='VIR_VCPU_BLOCKED' type='enum'/>
      <exports symbol='VIR_SECRET_USAGE_TYPE_NONE' type='enum'/>
      <exports symbol='VIR_DOMAIN_EVENT_STARTED_MIGRATED' type='enum'/>
      <exports symbol='VIR_STREAM_EVENT_HANGUP' type='enum'/>
@@ -83,6 +82,7 @@
      <exports symbol='VIR_STREAM_EVENT_WRITABLE' type='enum'/>
      <exports symbol='VIR_DOMAIN_SCHED_FIELD_DOUBLE' type='enum'/>
      <exports symbol='VIR_DOMAIN_SCHED_FIELD_LLONG' type='enum'/>
+     <exports symbol='VIR_VCPU_BLOCKED' type='enum'/>
      <exports symbol='VIR_DOMAIN_SCHED_FIELD_BOOLEAN' type='enum'/>
      <exports symbol='VIR_DOMAIN_XML_INACTIVE' type='enum'/>
      <exports symbol='VIR_STORAGE_VOL_BLOCK' type='enum'/>
@@ -2703,13 +2703,16 @@ should stop sending data.]]></info>
       <arg name='stream' type='virStreamPtr' info='pointer to the stream object'/>
     </function>
     <function name='virStreamEventAddCallback' file='libvirt' module='libvirt'>
-      <info><![CDATA[]]></info>
-      <return type='int' info=''/>
-      <arg name='stream' type='virStreamPtr' info=''/>
-      <arg name='events' type='int' info=''/>
-      <arg name='cb' type='virStreamEventCallback' info=''/>
-      <arg name='opaque' type='void *' info=''/>
-      <arg name='ff' type='virFreeCallback' info=''/>
+      <info><![CDATA[Register a callback to be notified when a stream
+becomes writable, or readable. This is most commonly
+used in conjunction with non-blocking data streams
+to integrate into an event loop]]></info>
+      <return type='int' info='0 on success, -1 upon error'/>
+      <arg name='stream' type='virStreamPtr' info='pointer to the stream object'/>
+      <arg name='events' type='int' info='set of events to monitor'/>
+      <arg name='cb' type='virStreamEventCallback' info='callback to invoke when an event occurs'/>
+      <arg name='opaque' type='void *' info='application defined data'/>
+      <arg name='ff' type='virFreeCallback' info='callback to free @opaque data'/>
     </function>
     <functype name='virStreamEventCallback' file='libvirt' module='libvirt'>
       <info><![CDATA[Callback for receiving stream events. The callback will
@@ -2720,15 +2723,18 @@ be invoked once for each event which is pending.]]></info>
       <arg name='opaque' type='void *' info='user data registered with handle'/>
     </functype>
     <function name='virStreamEventRemoveCallback' file='libvirt' module='libvirt'>
-      <info><![CDATA[]]></info>
-      <return type='int' info=''/>
-      <arg name='stream' type='virStreamPtr' info=''/>
+      <info><![CDATA[Remove a event callback from the stream]]></info>
+      <return type='int' info='0 on success, -1 on error'/>
+      <arg name='stream' type='virStreamPtr' info='pointer to the stream object'/>
     </function>
     <function name='virStreamEventUpdateCallback' file='libvirt' module='libvirt'>
-      <info><![CDATA[]]></info>
-      <return type='int' info=''/>
-      <arg name='stream' type='virStreamPtr' info=''/>
-      <arg name='events' type='int' info=''/>
+      <info><![CDATA[Changes the set of events to monitor for a stream. This allows
+for event notification to be changed without having to
+unregister & register the callback completely. This method
+is guarenteed to succeed if a callback is already registered]]></info>
+      <return type='int' info='0 on success, -1 if no callback is registered'/>
+      <arg name='stream' type='virStreamPtr' info='pointer to the stream object'/>
+      <arg name='events' type='int' info='set of events to monitor'/>
     </function>
     <function name='virStreamFinish' file='libvirt' module='libvirt'>
       <info><![CDATA[Indicate that there is no further data is to be transmitted
diff --git a/docs/libvirt-refs.xml b/docs/libvirt-refs.xml
index e7fbedf8c5..428f847588 100644
--- a/docs/libvirt-refs.xml
+++ b/docs/libvirt-refs.xml
@@ -2151,6 +2151,9 @@
         <word name='Change'>
           <ref name='virDomainSetSchedulerParameters'/>
         </word>
+        <word name='Changes'>
+          <ref name='virStreamEventUpdateCallback'/>
+        </word>
         <word name='Collect'>
           <ref name='virConnectListDefinedInterfaces'/>
           <ref name='virConnectListDomains'/>
@@ -2673,6 +2676,9 @@
         <word name='Refer'>
           <ref name='virDomainMigrate'/>
         </word>
+        <word name='Register'>
+          <ref name='virStreamEventAddCallback'/>
+        </word>
         <word name='Registering'>
           <ref name='virConnectDomainEventRegister'/>
         </word>
@@ -2683,6 +2689,9 @@
         <word name='Remaining'>
           <ref name='_virStoragePoolInfo'/>
         </word>
+        <word name='Remove'>
+          <ref name='virStreamEventRemoveCallback'/>
+        </word>
         <word name='Removes'>
           <ref name='virConnectDomainEventDeregister'/>
         </word>
@@ -3152,12 +3161,14 @@
         <word name='allows'>
           <ref name='virDomainBlockPeek'/>
           <ref name='virDomainMemoryPeek'/>
+          <ref name='virStreamEventUpdateCallback'/>
         </word>
         <word name='already'>
           <ref name='virConnectOpen'/>
           <ref name='virDomainDefineXML'/>
           <ref name='virDomainDestroy'/>
           <ref name='virNetworkDestroy'/>
+          <ref name='virStreamEventUpdateCallback'/>
           <ref name='virStreamRecvAll'/>
           <ref name='virStreamSendAll'/>
         </word>
@@ -3213,6 +3224,7 @@
           <ref name='virDomainGetMaxMemory'/>
           <ref name='virDomainSetMaxMemory'/>
           <ref name='virDomainSetMemory'/>
+          <ref name='virStreamEventAddCallback'/>
           <ref name='virStreamFinish'/>
           <ref name='virStreamNew'/>
           <ref name='virStreamRecv'/>
@@ -3405,6 +3417,9 @@
         <word name='because'>
           <ref name='virDomainMemoryPeek'/>
         </word>
+        <word name='becomes'>
+          <ref name='virStreamEventAddCallback'/>
+        </word>
         <word name='been'>
           <ref name='virStreamAbort'/>
           <ref name='virStreamFinish'/>
@@ -3688,6 +3703,9 @@
           <ref name='virEventUpdateHandleFunc'/>
           <ref name='virStoragePoolFree'/>
         </word>
+        <word name='changed'>
+          <ref name='virStreamEventUpdateCallback'/>
+        </word>
         <word name='char'>
           <ref name='virConnectListDefinedStoragePools'/>
           <ref name='virConnectListStoragePools'/>
@@ -3747,6 +3765,9 @@
         <word name='com'>
           <ref name='virConnectGetType'/>
         </word>
+        <word name='commonly'>
+          <ref name='virStreamEventAddCallback'/>
+        </word>
         <word name='communicating'>
           <ref name='virStoragePoolRefresh'/>
         </word>
@@ -3764,6 +3785,9 @@
         <word name='completed'>
           <ref name='virDomainBlockPeek'/>
         </word>
+        <word name='completely'>
+          <ref name='virStreamEventUpdateCallback'/>
+        </word>
         <word name='completion'>
           <ref name='virStreamRecv'/>
         </word>
@@ -3800,6 +3824,7 @@
           <ref name='VIR_GET_CPUMAP'/>
           <ref name='VIR_UNUSE_CPU'/>
           <ref name='VIR_USE_CPU'/>
+          <ref name='virStreamEventAddCallback'/>
         </word>
         <word name='conn'>
           <ref name='virStreamRecv'/>
@@ -4040,6 +4065,7 @@
           <ref name='virNetworkCreate'/>
           <ref name='virNetworkUndefine'/>
           <ref name='virSecretGetUsageType'/>
+          <ref name='virStreamEventAddCallback'/>
           <ref name='virStreamRecvAll'/>
           <ref name='virStreamSendAll'/>
         </word>
@@ -4426,7 +4452,10 @@
           <ref name='virEventHandleCallback'/>
           <ref name='virEventTimeoutCallback'/>
           <ref name='virEventUpdateTimeoutFunc'/>
+          <ref name='virStreamEventAddCallback'/>
           <ref name='virStreamEventCallback'/>
+          <ref name='virStreamEventRemoveCallback'/>
+          <ref name='virStreamEventUpdateCallback'/>
         </word>
         <word name='events'>
           <ref name='virConnectDomainEventDeregister'/>
@@ -4435,7 +4464,9 @@
           <ref name='virEventHandleCallback'/>
           <ref name='virEventTimeoutCallback'/>
           <ref name='virEventUpdateHandleFunc'/>
+          <ref name='virStreamEventAddCallback'/>
           <ref name='virStreamEventCallback'/>
+          <ref name='virStreamEventUpdateCallback'/>
         </word>
         <word name='ever'>
           <ref name='virSecretGetUsageID'/>
@@ -4781,6 +4812,9 @@
           <ref name='virStreamRecv'/>
           <ref name='virStreamSend'/>
         </word>
+        <word name='guarenteed'>
+          <ref name='virStreamEventUpdateCallback'/>
+        </word>
         <word name='guest'>
           <ref name='virConnectGetMaxVcpus'/>
           <ref name='virDomainCreateXML'/>
@@ -4861,6 +4895,7 @@
           <ref name='virStorageVolRef'/>
         </word>
         <word name='having'>
+          <ref name='virStreamEventUpdateCallback'/>
           <ref name='virStreamRecvAll'/>
           <ref name='virStreamSendAll'/>
         </word>
@@ -5123,6 +5158,9 @@
         <word name='integer'>
           <ref name='virSecretGetUsageType'/>
         </word>
+        <word name='integrate'>
+          <ref name='virStreamEventAddCallback'/>
+        </word>
         <word name='intended'>
           <ref name='virSecretGetUsageID'/>
         </word>
@@ -5145,12 +5183,14 @@
           <ref name='virConnectDomainEventRegister'/>
           <ref name='virSaveLastError'/>
           <ref name='virStoragePoolGetXMLDesc'/>
+          <ref name='virStreamEventAddCallback'/>
         </word>
         <word name='invalid'>
           <ref name='virConnCopyLastError'/>
           <ref name='virConnGetLastError'/>
         </word>
         <word name='invoke'>
+          <ref name='virStreamEventAddCallback'/>
           <ref name='virStreamRecv'/>
           <ref name='virStreamRecvAll'/>
           <ref name='virStreamSendAll'/>
@@ -5472,6 +5512,9 @@
           <ref name='virSecretLookupByUUIDString'/>
           <ref name='virSecretLookupByUsage'/>
         </word>
+        <word name='loop'>
+          <ref name='virStreamEventAddCallback'/>
+        </word>
         <word name='lowest'>
           <ref name='virDomainPinVcpu'/>
         </word>
@@ -5623,6 +5666,8 @@
         </word>
         <word name='monitor'>
           <ref name='virEventAddTimeoutFunc'/>
+          <ref name='virStreamEventAddCallback'/>
+          <ref name='virStreamEventUpdateCallback'/>
         </word>
         <word name='monitoring'>
           <ref name='virConnectClose'/>
@@ -5642,6 +5687,7 @@
         <word name='most'>
           <ref name='virNodeGetFreeMemory'/>
           <ref name='virStoragePoolListVolumes'/>
+          <ref name='virStreamEventAddCallback'/>
         </word>
         <word name='moves'>
           <ref name='virDomainCreate'/>
@@ -5803,6 +5849,7 @@
           <ref name='virNodeNumOfDevices'/>
         </word>
         <word name='non-blocking'>
+          <ref name='virStreamEventAddCallback'/>
           <ref name='virStreamNew'/>
           <ref name='virStreamRecv'/>
           <ref name='virStreamSend'/>
@@ -5827,9 +5874,13 @@
           <ref name='virConnectOpenAuth'/>
           <ref name='virConnectOpenReadOnly'/>
         </word>
+        <word name='notification'>
+          <ref name='virStreamEventUpdateCallback'/>
+        </word>
         <word name='notified'>
           <ref name='virEventRemoveHandleFunc'/>
           <ref name='virEventUpdateHandleFunc'/>
+          <ref name='virStreamEventAddCallback'/>
         </word>
         <word name='notify'>
           <ref name='virStreamNew'/>
@@ -5885,6 +5936,7 @@
         </word>
         <word name='occurs'>
           <ref name='virConnectDomainEventCallback'/>
+          <ref name='virStreamEventAddCallback'/>
         </word>
         <word name='offline'>
           <ref name='_virVcpuInfo'/>
@@ -6394,6 +6446,9 @@
           <ref name='virStreamSend'/>
           <ref name='virStreamSendAll'/>
         </word>
+        <word name='readable'>
+          <ref name='virStreamEventAddCallback'/>
+        </word>
         <word name='reading'>
           <ref name='virStreamSendAll'/>
         </word>
@@ -6440,6 +6495,9 @@
         <word name='refreshed'>
           <ref name='virStoragePoolRefresh'/>
         </word>
+        <word name='register'>
+          <ref name='virStreamEventUpdateCallback'/>
+        </word>
         <word name='registered'>
           <ref name='virConnectDomainEventCallback'/>
           <ref name='virEventAddHandleFunc'/>
@@ -6448,6 +6506,7 @@
           <ref name='virEventRemoveTimeoutFunc'/>
           <ref name='virEventTimeoutCallback'/>
           <ref name='virStreamEventCallback'/>
+          <ref name='virStreamEventUpdateCallback'/>
           <ref name='virStreamSend'/>
         </word>
         <word name='related'>
@@ -6861,6 +6920,8 @@
           <ref name='virSecretGetUsageID'/>
           <ref name='virSecretLookupByUsage'/>
           <ref name='virStoragePoolGetXMLDesc'/>
+          <ref name='virStreamEventAddCallback'/>
+          <ref name='virStreamEventUpdateCallback'/>
         </word>
         <word name='sets'>
           <ref name='virEventAddHandleFunc'/>
@@ -7087,6 +7148,7 @@
         </word>
         <word name='streams'>
           <ref name='virStreamAbort'/>
+          <ref name='virStreamEventAddCallback'/>
           <ref name='virStreamFinish'/>
         </word>
         <word name='structure'>
@@ -7112,6 +7174,7 @@
           <ref name='virDomainCreate'/>
           <ref name='virDomainMemoryPeek'/>
           <ref name='virNetworkCreate'/>
+          <ref name='virStreamEventUpdateCallback'/>
         </word>
         <word name='succesful'>
           <ref name='virStreamSend'/>
@@ -7473,6 +7536,9 @@
         <word name='unprivileged'>
           <ref name='virConnectOpen'/>
         </word>
+        <word name='unregister'>
+          <ref name='virStreamEventUpdateCallback'/>
+        </word>
         <word name='unregistered'>
           <ref name='virEventAddHandleFunc'/>
           <ref name='virEventAddTimeoutFunc'/>
@@ -7532,6 +7598,7 @@
           <ref name='virSecretGetUsageType'/>
           <ref name='virStoragePoolBuild'/>
           <ref name='virStreamAbort'/>
+          <ref name='virStreamEventAddCallback'/>
           <ref name='virStreamFinish'/>
           <ref name='virStreamFree'/>
           <ref name='virStreamNew'/>
@@ -8078,6 +8145,7 @@
           <ref name='virNetworkGetAutostart'/>
           <ref name='virNetworkSetAutostart'/>
           <ref name='virStoragePoolCreateXML'/>
+          <ref name='virStreamEventAddCallback'/>
           <ref name='virStreamFree'/>
           <ref name='virStreamRecv'/>
         </word>
@@ -8128,6 +8196,7 @@
         </word>
         <word name='without'>
           <ref name='virDomainSuspend'/>
+          <ref name='virStreamEventUpdateCallback'/>
         </word>
         <word name='won'>
           <ref name='virDomainBlockPeek'/>
@@ -8156,6 +8225,9 @@
           <ref name='virStoragePoolRef'/>
           <ref name='virStorageVolRef'/>
         </word>
+        <word name='writable'>
+          <ref name='virStreamEventAddCallback'/>
+        </word>
         <word name='write'>
           <ref name='_virDomainBlockStats'/>
           <ref name='virStreamRecv'/>
diff --git a/src/libvirt.c b/src/libvirt.c
index bcb89e191e..27d761d5dd 100644
--- a/src/libvirt.c
+++ b/src/libvirt.c
@@ -9802,7 +9802,7 @@ cleanup:
 
 
 /**
- * virStreamEventAddCallback
+ * virStreamEventAddCallback:
  * @stream: pointer to the stream object
  * @events: set of events to monitor
  * @cb: callback to invoke when an event occurs
@@ -9850,7 +9850,7 @@ error:
 
 
 /**
- * virStreamEventUpdateCallback
+ * virStreamEventUpdateCallback:
  * @stream: pointer to the stream object
  * @events: set of events to monitor
  *
@@ -9891,7 +9891,7 @@ error:
 }
 
 /**
- * virStreamEventRemoveCallback
+ * virStreamEventRemoveCallback:
  * @stream: pointer to the stream object
  *
  * Remove a event callback from the stream