diff options
-rw-r--r-- | ChangeLog | 9 | ||||
-rw-r--r-- | dbus/dbus-errors.c | 8 | ||||
-rw-r--r-- | dbus/dbus-memory.c | 112 | ||||
-rw-r--r-- | dbus/dbus-timeout.c | 2 | ||||
-rw-r--r-- | dbus/dbus-types.h | 31 | ||||
-rw-r--r-- | glib/dbus-gmain.c | 8 |
6 files changed, 134 insertions, 36 deletions
@@ -1,5 +1,14 @@ 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. diff --git a/dbus/dbus-errors.c b/dbus/dbus-errors.c index f7636287..3cf52363 100644 --- a/dbus/dbus-errors.c +++ b/dbus/dbus-errors.c @@ -39,7 +39,7 @@ * * @code * DBusError error; - * _dbus_error_init (&error); + * dbus_error_init (&error); * dbus_some_function (arg1, arg2, &error); * if (dbus_error_is_set (&error)) * { @@ -178,6 +178,8 @@ dbus_error_free (DBusError *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!!!) @@ -214,7 +216,7 @@ dbus_set_error_const (DBusError *error, * 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 */ @@ -288,6 +290,8 @@ dbus_error_is_set (const DBusError *error) * 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 * diff --git a/dbus/dbus-memory.c b/dbus/dbus-memory.c index c42ef466..dce1dded 100644 --- a/dbus/dbus-memory.c +++ b/dbus/dbus-memory.c @@ -27,7 +27,6 @@ #include "dbus-list.h" #include <stdlib.h> - /** * @defgroup DBusMemory Memory Allocation * @ingroup DBus @@ -36,6 +35,20 @@ * 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 + * * @{ */ @@ -74,6 +87,14 @@ * @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; @@ -387,6 +408,15 @@ set_guards (void *real_block, #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 @@ -625,6 +655,15 @@ dbus_free_string_array (char **str_array) } } +/** @} */ /* 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 @@ -652,36 +691,6 @@ _DBUS_DEFINE_GLOBAL_LOCK (shutdown_funcs); 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. * @@ -713,4 +722,43 @@ _dbus_register_shutdown_func (DBusShutdownFunction func, 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 */ diff --git a/dbus/dbus-timeout.c b/dbus/dbus-timeout.c index 1a2d2965..625fbb74 100644 --- a/dbus/dbus-timeout.c +++ b/dbus/dbus-timeout.c @@ -137,7 +137,7 @@ _dbus_timeout_set_interval (DBusTimeout *timeout, * 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, diff --git a/dbus/dbus-types.h b/dbus/dbus-types.h index e9bfca84..854b6526 100644 --- a/dbus/dbus-types.h +++ b/dbus/dbus-types.h @@ -77,6 +77,37 @@ typedef dbus_uint32_t dbus_unichar_t; * 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 */ diff --git a/glib/dbus-gmain.c b/glib/dbus-gmain.c index dd9ea375..c120a6c1 100644 --- a/glib/dbus-gmain.c +++ b/glib/dbus-gmain.c @@ -394,8 +394,11 @@ create_source (void *connection_or_server, /** * 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, @@ -446,11 +449,14 @@ 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; |