2003-04-29 Havoc Pennington <hp@redhat.com>
+ * glib/dbus-gmain.c: docs cleanups
+
+ * dbus/dbus-types.h: add docs on int64 types
+
+ * dbus/dbus-memory.c: fix docs to avoid putting private API in
+ public API docs section
+
+2003-04-29 Havoc Pennington <hp@redhat.com>
+
* dbus-1.pc.in, dbus-glib-1.pc.in: rename these from
dbus-1.0.pc.in, dbus-glib-1.0.pc.in. As these change with the
parallel install API version, not with the D-BUS package version.
*
* @code
* DBusError error;
- * _dbus_error_init (&error);
+ * dbus_error_init (&error);
* dbus_some_function (arg1, arg2, &error);
* if (dbus_error_is_set (&error))
* {
* message will be deduced from the name. If the error name is unknown
* to D-BUS the default message will be totally useless, though.
*
+ * @todo should be called dbus_error_set_const()
+ *
* @param error the error.
* @param name the error name (not copied!!!)
* @param message the error message (not copied!!!)
* src is reinitialized to an empty error. dest may not
* contain an existing error. If the destination is
* #NULL, just frees and reinits the source error.
- *
+ *
* @param src the source error
* @param dest the destination error or #NULL
*/
* If no memory can be allocated for the error message,
* an out-of-memory error message will be set instead.
*
+ * @todo should be called dbus_error_set()
+ *
* @todo stdio.h shouldn't be included in this file,
* should write _dbus_string_append_printf instead
*
#include "dbus-list.h"
#include <stdlib.h>
-
/**
* @defgroup DBusMemory Memory Allocation
* @ingroup DBus
* Functions and macros related to allocating and releasing
* blocks of memory.
*
+ */
+
+/**
+ * @defgroup DBusMemoryInternals Memory allocation implementation details
+ * @ingroup DBusInternals
+ * @brief internals of dbus_malloc() etc.
+ *
+ * Implementation details related to allocating and releasing blocks
+ * of memory.
+ */
+
+/**
+ * @addtogroup DBusMemory
+ *
* @{
*/
* @param memory the memory to free
*/
+/** @} */ /* end of public API docs */
+
+/**
+ * @addtogroup DBusMemoryInternals
+ *
+ * @{
+ */
+
#ifdef DBUS_BUILD_TESTS
static dbus_bool_t debug_initialized = FALSE;
static int fail_nth = -1;
#endif
+/** @} */ /* End of internals docs */
+
+
+/**
+ * @addtogroup DBusMemory
+ *
+ * @{
+ */
+
/**
* Allocates the given number of bytes, as with standard
* malloc(). Guaranteed to return #NULL if bytes is zero
}
}
+/** @} */ /* End of public API docs block */
+
+
+/**
+ * @addtogroup DBusMemoryInternals
+ *
+ * @{
+ */
+
/**
* _dbus_current_generation is used to track each
* time that dbus_shutdown() is called, so we can
static ShutdownClosure *registered_globals = NULL;
/**
- * The D-BUS library keeps some internal global variables, for example
- * to cache the username of the current process. This function is
- * used to free these global variables. It is really useful only for
- * leak-checking cleanliness and the like. WARNING: this function is
- * NOT thread safe, it must be called while NO other threads are using
- * D-BUS. You cannot continue using D-BUS after calling this function,
- * as it does things like free global mutexes created by
- * dbus_threads_init(). To use a D-BUS function after calling
- * dbus_shutdown(), you have to start over from scratch, e.g. calling
- * dbus_threads_init() again.
- */
-void
-dbus_shutdown (void)
-{
- while (registered_globals != NULL)
- {
- ShutdownClosure *c;
-
- c = registered_globals;
- registered_globals = c->next;
-
- (* c->func) (c->data);
-
- dbus_free (c);
- }
-
- _dbus_current_generation += 1;
-}
-
-/**
* Register a cleanup function to be called exactly once
* the next time dbus_shutdown() is called.
*
return TRUE;
}
-/** @} */
+/** @} */ /* End of private API docs block */
+
+
+/**
+ * @addtogroup DBusMemory
+ *
+ * @{
+ */
+
+/**
+ * The D-BUS library keeps some internal global variables, for example
+ * to cache the username of the current process. This function is
+ * used to free these global variables. It is really useful only for
+ * leak-checking cleanliness and the like. WARNING: this function is
+ * NOT thread safe, it must be called while NO other threads are using
+ * D-BUS. You cannot continue using D-BUS after calling this function,
+ * as it does things like free global mutexes created by
+ * dbus_threads_init(). To use a D-BUS function after calling
+ * dbus_shutdown(), you have to start over from scratch, e.g. calling
+ * dbus_threads_init() again.
+ */
+void
+dbus_shutdown (void)
+{
+ while (registered_globals != NULL)
+ {
+ ShutdownClosure *c;
+
+ c = registered_globals;
+ registered_globals = c->next;
+
+ (* c->func) (c->data);
+
+ dbus_free (c);
+ }
+
+ _dbus_current_generation += 1;
+}
+
+/** @} */ /** End of public API docs block */
* only used in the message bus daemon implementation.
*
* @param timeout the timeout
- * @param interval the new interval
+ * @param enabled #TRUE if timeout should be enabled.
*/
void
_dbus_timeout_set_enabled (DBusTimeout *timeout,
* A 16-bit signed integer on all platforms.
*/
+
+/**
+ * @typedef dbus_uint64_t
+ *
+ * A 64-bit unsigned integer on all platforms that support it.
+ * If supported, #DBUS_HAVE_INT64 will be defined.
+ */
+
+/**
+ * @typedef dbus_int64_t
+ *
+ * A 64-bit signed integer on all platforms that support it.
+ * If supported, #DBUS_HAVE_INT64 will be defined.
+ */
+
+/**
+ * @def DBUS_INT64_CONSTANT
+ *
+ * Declare a 64-bit signed integer constant. The macro
+ * adds the necessary "LL" or whatever after the integer,
+ * giving a literal such as "325145246765LL"
+ */
+
+/**
+ * @def DBUS_UINT64_CONSTANT
+ *
+ * Declare a 64-bit unsigned integer constant. The macro
+ * adds the necessary "ULL" or whatever after the integer,
+ * giving a literal such as "325145246765ULL"
+ */
+
/** @} */
#endif /* DBUS_TYPES_H */
/**
* Sets the watch and timeout functions of a #DBusConnection
* to integrate the connection with the GLib main loop.
+ * Pass in #NULL for the #GMainContext unless you're
+ * doing something specialized.
*
* @param connection the connection
+ * @param context the #GMainContext or #NULL for default context
*/
void
dbus_connection_setup_with_g_main (DBusConnection *connection,
/**
* Sets the watch and timeout functions of a #DBusServer
* to integrate the server with the GLib main loop.
+ * In most cases the context argument should be #NULL.
*
* @param server the server
+ * @param context the #GMainContext or #NULL for default
*/
void
-dbus_server_setup_with_g_main (DBusServer *server, GMainContext *context)
+dbus_server_setup_with_g_main (DBusServer *server,
+ GMainContext *context)
{
GSource *source;
projects / platform / upstream / dbus.git / commitdiff