diff options
Diffstat (limited to 'dbus/dbus.h')
| -rw-r--r-- | dbus/dbus.h | 42 |
1 files changed, 41 insertions, 1 deletions
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 <em>low-level</em> D-Bus C API. <b>If you use + * this low-level API directly, you're signing up for some pain.</b> + * + * 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 <a + * href="http://www.freedesktop.org/wiki/Software/dbus">the D-Bus + * website</a>. 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 + * <em>much</em> 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 */ |