[libvirt] doc nits

[Daniel Veillard]

On Tue, Nov 25, 2008 at 01:35:26PM +0100, Jim Meyering wrote:
> I noticed the following go by yesterday,
> but won't have time to address them:
> 
>   Function comment for virConnectDomainEventRegister lacks description of arg freecb
>   Function comment for virNodeDeviceGetName lacks description of the function
>   Function comment for virNodeDeviceGetParent lacks description of the function
>   Function comment for virNodeDeviceNumOfCaps lacks description of the function
>   Function comment for virNodeDeviceNumOfCaps lacks description of the function
>   Missing * in function comment for virDomainMigrateFinish
>   Missing * in function comment for virDomainMigrateFinish2
>   Missing * in function comment for virDomainMigratePerform
>   Missing * in function comment for virDomainMigratePrepare
>   Missing * in function comment for virDomainMigratePrepare2
>   Missing * in function comment for virDrvSupportsFeature

  Following patch should take care of those. For the last set they are
internal and the simplest was to extend apibuild.py with an
ignore_functions list

Daniel

-- 
Daniel Veillard      | libxml Gnome XML XSLT toolkit  http://xmlsoft.org/
daniel at veillard.com  | Rpmfind RPM search engine http://rpmfind.net/
http://veillard.com/ | virtualization library  http://libvirt.org/
-------------- next part --------------
Index: docs/apibuild.py
===================================================================
RCS file: /data/cvs/libxen/docs/apibuild.py,v
retrieving revision 1.25
diff -u -p -r1.25 apibuild.py
--- docs/apibuild.py	25 Jul 2008 08:52:19 -0000	1.25
+++ docs/apibuild.py	25 Nov 2008 13:32:36 -0000
@@ -29,6 +29,15 @@ ignored_words = {
   "VIR_DEPRECATED": (0, "macro keyword"),
 }
 
+ignored_functions = {
+  "virDomainMigrateFinish": "private function for migration",
+  "virDomainMigrateFinish2": "private function for migration",
+  "virDomainMigratePerform": "private function for migration",
+  "virDomainMigratePrepare": "private function for migration",
+  "virDomainMigratePrepare2": "private function for migration",
+  "virDrvSupportsFeature": "private function for remote access",
+}
+
 def escape(raw):
     raw = string.replace(raw, '&', '&')
     raw = string.replace(raw, '<', '<')
@@ -758,10 +767,14 @@ class CParser:
      # as possible
      #
     def mergeFunctionComment(self, name, description, quiet = 0):
+        global ignored_functions
+
         if name == 'main':
 	    quiet = 1
         if name[0:2] == '__':
 	    quiet = 1
+        if ignored_functions.has_key(name):
+            quiet = 1
 
 	(ret, args) = description
 	desc = ""
Index: src/libvirt.c
===================================================================
RCS file: /data/cvs/libxen/src/libvirt.c,v
retrieving revision 1.179
diff -u -p -r1.179 libvirt.c
--- src/libvirt.c	25 Nov 2008 10:31:52 -0000	1.179
+++ src/libvirt.c	25 Nov 2008 13:32:38 -0000
@@ -1046,7 +1046,8 @@ virConnectClose(virConnectPtr conn)
     return (0);
 }
 
-/* Not for public use.  This function is part of the internal
+/*
+ * Not for public use.  This function is part of the internal
  * implementation of driver features in the remote case.
  */
 int
@@ -2384,7 +2385,8 @@ virDomainMigrate (virDomainPtr domain,
     return ddomain;
 }
 
-/* Not for public use.  This function is part of the internal
+/*
+ * Not for public use.  This function is part of the internal
  * implementation of migration in the remote case.
  */
 int
@@ -2413,7 +2415,8 @@ virDomainMigratePrepare (virConnectPtr d
     return -1;
 }
 
-/* Not for public use.  This function is part of the internal
+/*
+ * Not for public use.  This function is part of the internal
  * implementation of migration in the remote case.
  */
 int
@@ -2443,7 +2446,8 @@ virDomainMigratePerform (virDomainPtr do
     return -1;
 }
 
-/* Not for public use.  This function is part of the internal
+/*
+ * Not for public use.  This function is part of the internal
  * implementation of migration in the remote case.
  */
 virDomainPtr
@@ -2471,7 +2475,8 @@ virDomainMigrateFinish (virConnectPtr dc
 }
 
 
-/* Not for public use.  This function is part of the internal
+/*
+ * Not for public use.  This function is part of the internal
  * implementation of migration in the remote case.
  */
 int
@@ -2502,7 +2507,8 @@ virDomainMigratePrepare2 (virConnectPtr 
     return -1;
 }
 
-/* Not for public use.  This function is part of the internal
+/*
+ * Not for public use.  This function is part of the internal
  * implementation of migration in the remote case.
  */
 virDomainPtr
@@ -5629,7 +5635,9 @@ char *virNodeDeviceGetXMLDesc(virNodeDev
  * virNodeDeviceGetName:
  * @dev: the device
  *
- * Returns the device name.
+ * Just return the device name
+ *
+ * Returns the device name or NULL in case of error
  */
 const char *virNodeDeviceGetName(virNodeDevicePtr dev)
 {
@@ -5647,6 +5655,8 @@ const char *virNodeDeviceGetName(virNode
  * virNodeDeviceGetParent:
  * @dev: the device
  *
+ * Accessor for the parent of the device
+ *
  * Returns the name of the device's parent, or NULL if the
  * device has no parent.
  */
@@ -5670,6 +5680,8 @@ const char *virNodeDeviceGetParent(virNo
  * virNodeDeviceNumOfCaps:
  * @dev: the device
  *
+ * Accessor for the number of capabilities supported by the device.
+ *
  * Returns the number of capabilities supported by the device.
  */
 int virNodeDeviceNumOfCaps(virNodeDevicePtr dev)
@@ -5750,6 +5762,7 @@ int virNodeDeviceFree(virNodeDevicePtr d
  * @conn: pointer to the connection
  * @cb: callback to the function handling domain events
  * @opaque: opaque data to pass on to the callback
+ * @freecb: optional function to deallocate opaque when not used anymore
  *
  * Adds a Domain Event Callback.
  * Registering for a domain callback will enable delivery of the events