hal/libhal libhal.c,1.57,1.58 libhal.h,1.32,1.33

David Zeuthen david at kemper.freedesktop.org
Sat Feb 25 12:38:25 PST 2006 

Update of /cvs/hal/hal/libhal
In directory kemper:/tmp/cvs-serv7058/libhal

Modified Files:
	libhal.c libhal.h 
Log Message:
2006-02-25  David Zeuthen  <davidz at redhat.com>

        * libhal/libhal.[ch]: Convert doc comments from Doxygen to gtk-doc

        * libhal-storage/libhal-storage.[ch]: Convert doc comments from
        Doxygen to gtk-doc (not completely done)

        * doc/api/hal-docs.xml: New file

        * doc/api/Doxyfile.in: Remove

        * doc/api/Makefile.am: Use gtk-doc instead of Doxygen

        * configure.in: Various cleanups; use gtk-doc instead of Doxygen

        * autogen.sh: Pass --enable-gtk-doc to configure.

        * acinclude.m4: Add GTK_DOC_CHECK, from cairo, thanks.



Index: libhal.c
===================================================================
RCS file: /cvs/hal/hal/libhal/libhal.c,v
retrieving revision 1.57
retrieving revision 1.58
diff -u -d -r1.57 -r1.58
--- libhal.c	12 Feb 2006 21:47:28 -0000	1.57
+++ libhal.c	25 Feb 2006 20:38:23 -0000	1.58
@@ -59,17 +59,11 @@
 
 
 
-/**
- * @defgroup LibHal HAL convenience library
- * @brief A convenience library used to communicate with the HAL daemon
- *	  using D-BUS
- *
- *  @{
- */
-
[...1889 lines suppressed...]
  *
- *  @param  ctx                 Context for connection to hald
- *  @param  udi                 Unique Device Id
- *  @param  condition_name      User-readable name of condition
- *  @param  condition_details   User-readable details of condition
- *  @param  error               Pointer to an initialized dbus error object for 
- *                              returning errors or NULL
- *  @return                     TRUE if condition successfully emitted,
+ * Emit a condition from a device.
+ *
+ * Returns: TRUE if condition successfully emitted,
  *                              FALSE otherwise
  */
 dbus_bool_t libhal_device_emit_condition (LibHalContext *ctx,
@@ -3365,5 +3365,3 @@
 
 	return result;	
 }
-
-/** @} */

Index: libhal.h
===================================================================
RCS file: /cvs/hal/hal/libhal/libhal.h,v
retrieving revision 1.32
retrieving revision 1.33
diff -u -d -r1.32 -r1.33
--- libhal.h	12 Feb 2006 21:47:28 -0000	1.32
+++ libhal.h	25 Feb 2006 20:38:23 -0000	1.33
@@ -35,7 +35,13 @@
 #endif
 #endif
 
-/** Checks if LibHalContext *ctx == NULL */
+/**
+ * LIBHAL_CHECK_LIBHALCONTEXT:
+ * @_ctx_: the context
+ * @_ret_: what to use for return value if context is invalid
+ *
+ * Handy macro for checking whether a context is valid.
+ */
 #define LIBHAL_CHECK_LIBHALCONTEXT(_ctx_, _ret_)					\
 	do {									\
 		if (_ctx_ == NULL) {						\
@@ -46,16 +52,14 @@
 		}								\
 	} while(0)
 
-/**
- * @addtogroup LibHal
+/** 
+ * LibHalPropertyType:
  *
- * @{
+ * Possible types for properties on hal device objects 
  */
-
-/** Possible types for properties on hal device objects */
 typedef enum {
         /** Used to report error condition */
-	LIBHAL_PROPERTY_TYPE_INVALID     =    DBUS_TYPE_INVALID,
+	LIBHAL_PROPERTY_TYPE_INVALID =    DBUS_TYPE_INVALID,
 
 	/** Type for 32-bit signed integer property */
 	LIBHAL_PROPERTY_TYPE_INT32   =    DBUS_TYPE_INT32,
@@ -73,65 +77,75 @@
 	LIBHAL_PROPERTY_TYPE_STRING  =    DBUS_TYPE_STRING,
 
 	/** Type for list of UTF-8 strings property */
-	LIBHAL_PROPERTY_TYPE_STRLIST =     ((int) (DBUS_TYPE_STRING<<8)+('l'))
+	LIBHAL_PROPERTY_TYPE_STRLIST =    ((int) (DBUS_TYPE_STRING<<8)+('l'))
 } LibHalPropertyType;
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
-typedef struct LibHalContext_s LibHalContext;
-#endif /* DOXYGEN_SHOULD_SKIP_THIS */
-
-/** Type for function in application code that integrates a DBusConnection 
- *  object into its own mainloop.
+/** 
+ * LibHalIntegrateDBusIntoMainLoop:
+ * @ctx: context for connection to hald
+ * @dbus_connection: DBus connection to use in ctx
  *
- *  @param  ctx                 Context for connection to hald
- *  @param  dbus_connection     DBus connection to use in ctx
+ * Type for function in application code that integrates a
+ * DBusConnection object into its own mainloop.
  */
 typedef void (*LibHalIntegrateDBusIntoMainLoop) (LibHalContext *ctx,
 						 DBusConnection *dbus_connection);
 
-/** Type for callback when a device is added.
+/** 
+ * LibHalDeviceAdded:
+ * @ctx: context for connection to hald
+ * @udi: the Unique Device Id
  *
- *  @param  ctx                 Context for connection to hald
- *  @param  udi                 Unique Device Id
+ * Type for callback when a device is added.
  */
 typedef void (*LibHalDeviceAdded) (LibHalContext *ctx, 
 				   const char *udi);
 
-/** Type for callback when a device is removed. 
+/** 
+ * LibHalDeviceRemoved:
+ * @ctx: context for connection to hald
+ * @udi: the Unique Device Id
  *
- *  @param  ctx                 Context for connection to hald
- *  @param  udi                 Unique Device Id
+ * Type for callback when a device is removed. 
  */
 typedef void (*LibHalDeviceRemoved) (LibHalContext *ctx, 
 				     const char *udi);
 
-/** Type for callback when a device gains a new capability
+/** 
+ * LibHalDeviceNewCapability:
+ * @ctx: context for connection to hald
+ * @udi: the Unique Device Id
+ * @capability: capability of the device
+ *
+ * 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
  */
 typedef void (*LibHalDeviceNewCapability) (LibHalContext *ctx, 
 					   const char *udi,
 					   const char *capability);
 
-/** Type for callback when a device loses a capability
+/** 
+ * LibHalDeviceLostCapability:
+ * @ctx: context for connection to hald
+ * @udi: the Unique Device Id
+ * @capability: capability of the device
+ *
+ * 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
  */
 typedef void (*LibHalDeviceLostCapability) (LibHalContext *ctx, 
 					    const char *udi,
 					    const char *capability);
 
-/** Type for callback when a property of a device changes. 
+/** 
+ * LibHalDevicePropertyModified:
+ * @ctx: context for connection to hald
+ * @udi: the Unique Device Id
+ * @key: name of the property that has changed
+ * @is_removed: whether or not property was removed
+ * @is_added: whether or not property was added
  *
- *  @param  ctx                 Context for connection to hald
- *  @param  udi                 Unique Device Id
- *  @param  key                 Name of the property that has changed
- *  @param  is_removed          Whether or not property was removed
- *  @param  is_added            Whether or not property was added
+ * Type for callback when a property of a device changes. 
  */
 typedef void (*LibHalDevicePropertyModified) (LibHalContext *ctx,
 					      const char *udi,
@@ -139,14 +153,14 @@
 					      dbus_bool_t is_removed,
 					      dbus_bool_t is_added);
 
-/** Type for callback when a non-continuous condition occurs on a device
+/** 
+ * LibHalDeviceCondition:
+ * @ctx: context for connection to hald
+ * @udi: the Unique Device Id
+ * @condition_name: name of the condition, e.g. ProcessorOverheating. Consult the HAL spec for details
+ * @condition_detail: detail of condition
  *
- *  @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  condition_detail    User-readable details of condition
+ * Type for callback when a non-continuous condition occurs on a device.
  */
 typedef void (*LibHalDeviceCondition) (LibHalContext *ctx,
 				       const char *udi,
@@ -306,7 +320,7 @@
 dbus_bool_t libhal_device_property_strlist_remove_index (LibHalContext *ctx, 
 							 const char *udi,
 							 const char *key,
-							 unsigned int index,
+							 unsigned int idx,
 							 DBusError *error);
 
 /* Remove a specified string from a property of type strlist. */
@@ -348,19 +362,20 @@
 /* Get the number of properties in a property set. */
 unsigned int libhal_property_set_get_num_elems (LibHalPropertySet *set);
 
-/** Iterator for inspecting all properties */
+/** 
+ * LibHalPropertySetIterator: 
+ * 
+ * Iterator for inspecting all properties. Do not access any members;
+ * use the libhal_psi_* family of functions instead.
+ */
 struct LibHalPropertySetIterator_s {
 	LibHalPropertySet *set;    /**< Property set we are iterating over */
-	unsigned int index;        /**< Index into current element */
+	unsigned int idx;          /**< Index into current element */
 	LibHalProperty *cur_prop;  /**< Current property being visited */
 	void *reservered0;         /**< Reserved for future use */
 	void *reservered1;         /**< Reserved for future use */
 };
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
-typedef struct LibHalPropertySetIterator_s LibHalPropertySetIterator;
-#endif /* DOXYGEN_SHOULD_SKIP_THIS */
-
 /* Initialize a property set iterator. */
 void libhal_psi_init (LibHalPropertySetIterator *iter, LibHalPropertySet *set);
 
@@ -512,7 +527,6 @@
 					  const char *condition_details,
 					  DBusError *error);
 
-/** @} */
 
 #if defined(__cplusplus)
 }

More information about the hal-commit mailing list