Patch from Rohan McGovern <rohan.pm@gmail.com> to fix up Doxygen

    documentation. Thanks!

1 files changed, 121 insertions, 17 deletions

diff --git a/libhal/libhal.h b/libhal/libhal.h
index 48b2b7a9..0c8b61f9 100644
--- a/libhal/libhal.h
+++ b/libhal/libhal.h
@@ -70,15 +70,17 @@ typedef struct LibHalContext_s LibHalContext;
 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 
 /** Type for function in application code that integrates a DBusConnection 
- *  object into it's own mainloop. 
+ *  object into its own mainloop.
  *
- *  @param  udi                 Unique Device Id
+ *  @param  ctx                 Context for connection to hald
+ *  @param  dbus_connection     DBus connection to use in ctx
  */
 typedef void (*LibHalIntegrateDBusIntoMainLoop) (LibHalContext *ctx,
 						 DBusConnection *dbus_connection);
 
 /** Type for callback when a device is added.
  *
+ *  @param  ctx                 Context for connection to hald
  *  @param  udi                 Unique Device Id
  */
 typedef void (*LibHalDeviceAdded) (LibHalContext *ctx, 
@@ -86,6 +88,7 @@ typedef void (*LibHalDeviceAdded) (LibHalContext *ctx,
 
 /** Type for callback when a device is removed. 
  *
+ *  @param  ctx                 Context for connection to hald
  *  @param  udi                 Unique Device Id
  */
 typedef void (*LibHalDeviceRemoved) (LibHalContext *ctx, 
@@ -93,6 +96,7 @@ typedef void (*LibHalDeviceRemoved) (LibHalContext *ctx,
 
 /** Type for callback when a device gains a new capability
  *
+ *  @param  ctx                 Context for connection to hald
  *  @param  udi                 Unique Device Id
  *  @param  capability          Capability of the device
  */
@@ -102,6 +106,7 @@ typedef void (*LibHalDeviceNewCapability) (LibHalContext *ctx,
 
 /** Type for callback when a device loses a capability
  *
+ *  @param  ctx                 Context for connection to hald
  *  @param  udi                 Unique Device Id
  *  @param  capability          Capability of the device
  */
@@ -111,10 +116,11 @@ typedef void (*LibHalDeviceLostCapability) (LibHalContext *ctx,
 
 /** Type for callback when a property of a device changes. 
  *
+ *  @param  ctx                 Context for connection to hald
  *  @param  udi                 Unique Device Id
  *  @param  key                 Name of the property that has changed
- *  @param  is_removed          Property removed
- *  @param  is_added            Property added
+ *  @param  is_removed          Whether or not property was removed
+ *  @param  is_added            Whether or not property was added
  */
 typedef void (*LibHalDevicePropertyModified) (LibHalContext *ctx,
 					      const char *udi,
@@ -122,14 +128,14 @@ typedef void (*LibHalDevicePropertyModified) (LibHalContext *ctx,
 					      dbus_bool_t is_removed,
 					      dbus_bool_t is_added);
 
-/** Type for callback when a non-continuos condition occurs on a device
+/** Type for callback when a non-continuous condition occurs on a device
  *
+ *  @param  ctx                 Context for connection to hald
  *  @param  udi                 Unique Device Id
  *  @param  condition_name      Name of the condition, e.g. 
  *                              ProcessorOverheating. Consult the HAL spec
  *                              for possible conditions
- *  @param  message             D-BUS message with variable parameters
- *                              depending on condition
+ *  @param  condition_detail    User-readable details of condition
  */
 typedef void (*LibHalDeviceCondition) (LibHalContext *ctx,
 				       const char *udi,
@@ -137,128 +143,172 @@ typedef void (*LibHalDeviceCondition) (LibHalContext *ctx,
 				       const char *condition_detail);
 
 
+/* Create a new context for a connection with hald */
 LibHalContext *libhal_ctx_new                          (void);
+
+/* Enable or disable caching */
 dbus_bool_t    libhal_ctx_set_cache                    (LibHalContext *ctx, dbus_bool_t use_cache);
+
+/* Set DBus connection to use to talk to hald. */
 dbus_bool_t    libhal_ctx_set_dbus_connection          (LibHalContext *ctx, DBusConnection *conn);
+
+/* Set user data for the context */
 dbus_bool_t    libhal_ctx_set_user_data                (LibHalContext *ctx, void *user_data);
+
+/* Get user data for the context */
 void*          libhal_ctx_get_user_data                (LibHalContext *ctx);
+
+/* Set the callback for when a device is added */
 dbus_bool_t    libhal_ctx_set_device_added             (LibHalContext *ctx, LibHalDeviceAdded callback);
+
+/* Set the callback for when a device is removed */
 dbus_bool_t    libhal_ctx_set_device_removed           (LibHalContext *ctx, LibHalDeviceRemoved callback);
+
+/* Set the callback for when a device gains a new capability */
 dbus_bool_t    libhal_ctx_set_device_new_capability    (LibHalContext *ctx, LibHalDeviceNewCapability callback);
+
+/* Set the callback for when a device loses a capability */
 dbus_bool_t    libhal_ctx_set_device_lost_capability   (LibHalContext *ctx, LibHalDeviceLostCapability callback);
+
+/* Set the callback for when a property is modified on a device */
 dbus_bool_t    libhal_ctx_set_device_property_modified (LibHalContext *ctx, LibHalDevicePropertyModified callback);
+
+/* Set the callback for when a device emits a condition */
 dbus_bool_t    libhal_ctx_set_device_condition         (LibHalContext *ctx, LibHalDeviceCondition callback);
+
+/* Initialize the connection to hald */
 dbus_bool_t    libhal_ctx_init                         (LibHalContext *ctx, DBusError *error);
+
+/* Shut down a connection to hald */
 dbus_bool_t    libhal_ctx_shutdown                     (LibHalContext *ctx, DBusError *error);
+
+/* Free a LibHalContext resource */
 dbus_bool_t    libhal_ctx_free                         (LibHalContext *ctx);
 
+/* Create an already initialized connection to hald */
 LibHalContext *libhal_ctx_init_direct                  (DBusError *error);
 
-
+/* Get all devices in the Global Device List (GDL). */
 char        **libhal_get_all_devices (LibHalContext *ctx, int *num_devices, DBusError *error);
+
+/* Determine if a device exists. */
 dbus_bool_t   libhal_device_exists   (LibHalContext *ctx, const char *udi,  DBusError *error);
+
+/* Print a device to stdout; useful for debugging. */
 dbus_bool_t   libhal_device_print    (LibHalContext *ctx, const char *udi,  DBusError *error);
 
+/* Determine if a property on a device exists. */
 dbus_bool_t libhal_device_property_exists (LibHalContext *ctx, 
 					   const char *udi,
 					   const char *key,
 					   DBusError *error);
 
-
+/* Get the value of a property of type string. */
 char *libhal_device_get_property_string (LibHalContext *ctx, 
 					 const char *udi,
 					 const char *key,
 					 DBusError *error);
 
+/* Get the value of a property of type signed integer. */
 dbus_int32_t libhal_device_get_property_int (LibHalContext *ctx, 
 					     const char *udi,
 					     const char *key,
 					     DBusError *error);
 
+/* Get the value of a property of type unsigned integer. */
 dbus_uint64_t libhal_device_get_property_uint64 (LibHalContext *ctx, 
 						 const char *udi,
 						 const char *key,
 						 DBusError *error);
 
+/* Get the value of a property of type double. */
 double libhal_device_get_property_double (LibHalContext *ctx, 
 					  const char *udi,
 					  const char *key,
 					  DBusError *error);
 
+/* Get the value of a property of type bool. */
 dbus_bool_t libhal_device_get_property_bool (LibHalContext *ctx, 
 					     const char *udi,
 					     const char *key,
 					     DBusError *error);
 
+/* Get the value of a property of type string list. */
 char **libhal_device_get_property_strlist (LibHalContext *ctx, 
 					   const char *udi, 
 					   const char *key,
 					   DBusError *error);
 
-
-
+/* Set a property of type string. */
 dbus_bool_t libhal_device_set_property_string (LibHalContext *ctx, 
 					       const char *udi,
 					       const char *key,
 					       const char *value,
 					       DBusError *error);
 
+/* Set a property of type signed integer. */
 dbus_bool_t libhal_device_set_property_int (LibHalContext *ctx, 
 					    const char *udi,
 					    const char *key,
 					    dbus_int32_t value,
 					    DBusError *error);
 
+/* Set a property of type unsigned integer. */
 dbus_bool_t libhal_device_set_property_uint64 (LibHalContext *ctx, 
 					       const char *udi,
 					       const char *key,
 					       dbus_uint64_t value,
 					       DBusError *error);
 
+/* Set a property of type double. */
 dbus_bool_t libhal_device_set_property_double (LibHalContext *ctx, 
 					       const char *udi,
 					       const char *key,
 					       double value,
 					       DBusError *error);
 
+/* Set a property of type bool. */
 dbus_bool_t libhal_device_set_property_bool (LibHalContext *ctx, 
 					     const char *udi,
 					     const char *key,
 					     dbus_bool_t value,
 					     DBusError *error);
 
-
+/* Append to a property of type strlist. */
 dbus_bool_t libhal_device_property_strlist_append (LibHalContext *ctx, 
 						   const char *udi,
 						   const char *key,
 						   const char *value,
 						   DBusError *error);
 
+/* Prepend to a property of type strlist. */
 dbus_bool_t libhal_device_property_strlist_prepend (LibHalContext *ctx, 
 						    const char *udi,
 						    const char *key,
 						    const char *value,
 						    DBusError *error);
 
+/* Remove a specified string from a property of type strlist. */
 dbus_bool_t libhal_device_property_strlist_remove_index (LibHalContext *ctx, 
 							 const char *udi,
 							 const char *key,
 							 unsigned int index,
 							 DBusError *error);
 
+/* Remove a specified string from a property of type strlist. */
 dbus_bool_t libhal_device_property_strlist_remove (LibHalContext *ctx, 
 						   const char *udi,
 						   const char *key,
 						   const char *value,
 						   DBusError *error);
 
-
-
+/* Remove a property. */
 dbus_bool_t libhal_device_remove_property (LibHalContext *ctx, 
 					   const char *udi,
 					   const char *key,
 					   DBusError *error);
 
+/* Query a property type of a device. */
 LibHalPropertyType libhal_device_get_property_type (LibHalContext *ctx, 
 						    const char *udi,
 						    const char *key,
@@ -273,13 +323,15 @@ struct LibHalPropertySet_s;
 typedef struct LibHalPropertySet_s LibHalPropertySet;
 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 
-
+/* Retrieve all the properties on a device. */
 LibHalPropertySet *libhal_device_get_all_properties (LibHalContext *ctx, 
 						     const char *udi,
 						     DBusError *error);
 
+/* Free a property set earlier obtained with libhal_device_get_all_properties(). */
 void libhal_free_property_set (LibHalPropertySet *set);
 
+/* Get the number of properties in a property set. */
 unsigned int libhal_property_set_get_num_elems (LibHalPropertySet *set);
 
 /** Iterator for inspecting all properties */
@@ -295,87 +347,138 @@ struct LibHalPropertySetIterator_s {
 typedef struct LibHalPropertySetIterator_s LibHalPropertySetIterator;
 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 
+/* Initialize a property set iterator. */
 void libhal_psi_init (LibHalPropertySetIterator *iter, LibHalPropertySet *set);
 
+/* Determine whether there are more properties to iterate over */
 dbus_bool_t libhal_psi_has_more (LibHalPropertySetIterator *iter);
+
+/* Advance iterator to next property. */
 void libhal_psi_next (LibHalPropertySetIterator *iter);
 
+/* Get type of property. */
 LibHalPropertyType libhal_psi_get_type (LibHalPropertySetIterator *iter);
 
+/* Get the key of a property. */
 char *libhal_psi_get_key (LibHalPropertySetIterator *iter);
 
+/* Get the value of a property of type string. */
 char *libhal_psi_get_string (LibHalPropertySetIterator *iter);
+
+/* Get the value of a property of type signed integer. */
 dbus_int32_t libhal_psi_get_int (LibHalPropertySetIterator *iter);
+
+/* Get the value of a property of type unsigned integer. */
 dbus_uint64_t libhal_psi_get_uint64 (LibHalPropertySetIterator *iter);
+
+/* Get the value of a property of type double. */
 double libhal_psi_get_double (LibHalPropertySetIterator *iter);
+
+/* Get the value of a property of type bool. */
 dbus_bool_t libhal_psi_get_bool (LibHalPropertySetIterator *iter);
+
+/* Get the value of a property of type string list. */
 char **libhal_psi_get_strlist (LibHalPropertySetIterator *iter);
 
+/* Get the length of an array of strings */
 unsigned int libhal_string_array_length (char **str_array);
 
+/* Frees a NULL-terminated array of strings. If passed NULL, does nothing. */
 void libhal_free_string_array (char **str_array);
-void libhal_free_string (char *str);
 
+/* Frees a nul-terminated string */
+void libhal_free_string (char *str);
 
+/* Create a new device object which will be hidden from applications
+ * until the CommitToGdl(), ie. libhal_agent_commit_to_gdl(), method is called.
+ */
 char *libhal_agent_new_device (LibHalContext *ctx, DBusError *error);
 
+/* When a hidden device has been built using the NewDevice method, ie.
+ * libhal_agent_new_device(), and the org.freedesktop.Hal.Device interface
+ * this function will commit it to the global device list. 
+ */
 dbus_bool_t libhal_agent_commit_to_gdl (LibHalContext *ctx,
 					const char *temp_udi,
 					const char *udi,
 					DBusError *error);
 
+/* This method can be invoked when a device is removed. The HAL daemon
+ * will shut down the device. Note that the device may still be in the device
+ * list if the Persistent property is set to true. 
+ */
 dbus_bool_t libhal_agent_remove_device (LibHalContext *ctx, 
 					const char *udi,
 					DBusError *error);
 
+/* Merge properties from one device to another. */
 dbus_bool_t libhal_agent_merge_properties (LibHalContext *ctx,
 					   const char *target_udi,
 					   const char *source_udi,
 					   DBusError *error);
 
+/* Check a set of properties for two devices matches. */
 dbus_bool_t libhal_agent_device_matches (LibHalContext *ctx,
 					 const char *udi1,
 					 const char *udi2,
 					 const char *property_namespace,
 					 DBusError *error);
 
+/* Find a device in the GDL where a single string property matches a
+ * given value.
+ */
 char **libhal_manager_find_device_string_match (LibHalContext *ctx,
 						const char *key,
 						const char *value,
 						int *num_devices,
 						DBusError *error);
 
-
+/* Assign a capability to a device. */
 dbus_bool_t libhal_device_add_capability (LibHalContext *ctx,
 					  const char *udi,
 					  const char *capability,
 					  DBusError *error);
 
+/* Check if a device has a capability. The result is undefined if the
+ * device doesn't exist.
+ */
 dbus_bool_t libhal_device_query_capability (LibHalContext *ctx,
 					    const char *udi,
 					    const char *capability,
 					    DBusError *error);
 
+/* Find devices with a given capability. */
 char **libhal_find_device_by_capability (LibHalContext *ctx,
 					 const char *capability,
 					 int *num_devices,
 					 DBusError *error);
 
+/* Watch all devices, ie. the device_property_changed callback is
+ * invoked when the properties on any device changes.
+ */
 dbus_bool_t libhal_device_property_watch_all (LibHalContext *ctx,
 					      DBusError *error);
+
+/* Add a watch on a device, so the device_property_changed callback is
+ * invoked when the properties on the given device changes.
+ */
 dbus_bool_t libhal_device_add_property_watch (LibHalContext *ctx, 
 					      const char *udi,
 					      DBusError *error);
+
+/* Remove a watch on a device */
 dbus_bool_t libhal_device_remove_property_watch (LibHalContext *ctx, 
 						 const char *udi,
 						 DBusError *error);
 
+/* Take an advisory lock on the device. */
 dbus_bool_t libhal_device_lock (LibHalContext *ctx,
 				const char *udi,
 				const char *reason_to_lock,
 				char **reason_why_locked,
 				DBusError *error);
 
+/* Release an advisory lock on the device. */
 dbus_bool_t libhal_device_unlock (LibHalContext *ctx,
 				  const char *udi,
 				  DBusError *error);
@@ -388,6 +491,7 @@ dbus_bool_t libhal_device_reprobe (LibHalContext *ctx,
 				   const char *udi,
 				   DBusError *error);
 
+/* Emit a condition from a device */
 dbus_bool_t libhal_device_emit_condition (LibHalContext *ctx,
 					  const char *udi,
 					  const char *condition_name,