From ebb239648b60872d0e840e6b4fd63af0eb7d0d5a Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Fri, 20 Oct 2006 05:16:58 +0000 Subject: 2006-10-20 Havoc Pennington * doc/TODO: remove the int64 thing from 1.0 since it doesn't matter, and the message-loader-breaker thing since nobody is going to do it. Add an item to 1.0 about supporting recursive locks in dbus_threads_init_default() though, since it should be easy. * dbus/dbus-connection.c (_dbus_connection_read_write_dispatch): Fix this in the !dispatch case to avoid busy-looping after disconnection * More misc docs improvements --- dbus/dbus.h | 42 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) (limited to 'dbus/dbus.h') diff --git a/dbus/dbus.h b/dbus/dbus.h index ac1287e8..c15ebac6 100644 --- a/dbus/dbus.h +++ b/dbus/dbus.h @@ -47,7 +47,7 @@ * @defgroup DBus D-Bus low-level public API * @brief The low-level public API of the D-Bus library * - * libdbus provides a low-level API intended primarily for use by + * libdbus provides a low-level C API intended primarily for use by * bindings to specific object systems and languages. D-Bus is most * convenient when used with the GLib bindings, Python bindings, Qt * bindings, Mono bindings, and so forth. This low-level API has a @@ -58,5 +58,45 @@ /** @} */ +/** + * @mainpage + * + * This manual documents the low-level D-Bus C API. If you use + * this low-level API directly, you're signing up for some pain. + * + * Caveats aside, you might get started learning the low-level API by reading + * about @ref DBusConnection and @ref DBusMessage. + * + * There are several other places to look for D-Bus information, such + * as the tutorial and the specification; those can be found at the D-Bus + * website. If you're interested in a sysadmin or package + * maintainer's perspective on the dbus-daemon itself and its + * configuration, be sure to check out the man pages as well. + * + * The low-level API documented in this manual deliberately lacks + * most convenience functions - those are left up to higher-level libraries + * based on frameworks such as GLib, Qt, Python, Mono, Java, + * etc. These higher-level libraries (often called "D-Bus bindings") + * have features such as object systems and main loops that allow a + * much more convenient API. + * + * The low-level API also contains plenty of clutter to support + * integration with arbitrary object systems, languages, main loops, + * and so forth. These features add a lot of noise to the API that you + * probably don't care about unless you're coding a binding. + * + * This manual also contains docs for @ref DBusInternals "D-Bus internals", + * so you can use it to get oriented to the D-Bus source code if you're + * interested in patching the code. You should also read the + * file HACKING which comes with the source code if you plan to contribute to + * D-Bus. + * + * As you read the code, you can identify internal D-Bus functions + * because they start with an underscore ('_') character. Also, any + * identifier or macro that lacks a DBus, dbus_, or DBUS_ namepace + * prefix is internal, with a couple of exceptions such as #NULL, + * #TRUE, and #FALSE. + */ #endif /* DBUS_H */ -- cgit