The first patch tells the doxygen preprocessor to parse D-Bus functions, as well as enabling transparent background in the generated dot images.
The second patch is a set of doxygen style comments for the D-Bus functions. Thanks, - Brian Gianforcaro
From 950f30540a874320bc39ed78a349a977cb00a73c Mon Sep 17 00:00:00 2001 From: Brian Gianforcaro <[email protected]> Date: Thu, 3 Sep 2009 17:18:54 -0400 Subject: [PATCH 1/2] awesome.doxygen: doxygen configuration fixes. * Set a #define for WITH_DBUS * Set dot to use transparent image backgrounds * Fix small typo Signed-off-by: Brian Gianforcaro <[email protected]> --- awesome.doxygen.in | 7 ++++--- 1 files changed, 4 insertions(+), 3 deletions(-) diff --git a/awesome.doxygen.in b/awesome.doxygen.in index 07c03e5..d6a5b92 100644 --- a/awesome.doxygen.in +++ b/awesome.doxygen.in @@ -203,7 +203,8 @@ EXPAND_ONLY_PREDEF = YES SEARCH_INCLUDES = YES INCLUDE_PATH = INCLUDE_FILE_PATTERNS = -PREDEFINED = "__attribute__(x)=" +PREDEFINED = WITH_DBUS = \ + "__attribute__(x)=" EXPAND_AS_DEFINED = SKIP_FUNCTION_MACROS = YES #--------------------------------------------------------------------------- @@ -225,7 +226,7 @@ CLASS_GRAPH = YES COLLABORATION_GRAPH = YES GROUP_GRAPHS = YES UML_LOOK = YES -TEMPLATE_RELATIONS = YeS +TEMPLATE_RELATIONS = YES INCLUDE_GRAPH = YES INCLUDED_BY_GRAPH = YES CALL_GRAPH = YES @@ -237,7 +238,7 @@ DOT_PATH = DOTFILE_DIRS = DOT_GRAPH_MAX_NODES = 50 MAX_DOT_GRAPH_DEPTH = 1000 -DOT_TRANSPARENT = NO +DOT_TRANSPARENT = YES DOT_MULTI_TARGETS = NO GENERATE_LEGEND = YES DOT_CLEANUP = YES -- 1.6.3.3
From 63b602933955d1d11f98da917c36aaca1c70dfb8 Mon Sep 17 00:00:00 2001 From: Brian Gianforcaro <[email protected]> Date: Fri, 4 Sep 2009 10:31:29 -0400 Subject: [PATCH 2/2] Added documentation to D-Bus functions. Signed-off-by: Brian Gianforcaro <[email protected]> --- dbus.c | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 files changed, 55 insertions(+), 1 deletions(-) diff --git a/dbus.c b/dbus.c index 7c6572d..fb25337 100644 --- a/dbus.c +++ b/dbus.c @@ -39,6 +39,10 @@ ev_io dbusio_sys = { .fd = -1 }; static signal_array_t dbus_signals; +/** Clean up the D-Bus connection data members + * \param dbus_connection The D-Bus connection to clean up + * \param dbusio The D-Bus event watcher + */ static void a_dbus_cleanup_bus(DBusConnection *dbus_connection, ev_io *dbusio) { @@ -58,6 +62,10 @@ a_dbus_cleanup_bus(DBusConnection *dbus_connection, ev_io *dbusio) dbus_connection_unref(dbus_connection); } +/** Iterate through the D-Bus messages counting each or traverse each sub message. + * \param iter The D-Bus message iterator pointer + * \return The number of arguments in the iterator + */ static int a_dbus_message_iter(DBusMessageIter *iter) { @@ -248,6 +256,10 @@ a_dbus_message_iter(DBusMessageIter *iter) return nargs; } +/** Process a single request from D-Bus + * \param dbus_connection The connection to the D-Bus server. + * \param msg The D-Bus message request being sent to the D-Bus connection. + */ static void a_dbus_process_request(DBusConnection *dbus_connection, DBusMessage *msg) { @@ -380,6 +392,10 @@ a_dbus_process_request(DBusConnection *dbus_connection, DBusMessage *msg) } } +/** Attempt to process all the requests in the D-Bus connection. + * \param dbus_connection The D-Bus connection to process from + * \param dbusio The D-Bus event watcher + */ static void a_dbus_process_requests_on_bus(DBusConnection *dbus_connection, ev_io *dbusio) { @@ -411,18 +427,32 @@ a_dbus_process_requests_on_bus(DBusConnection *dbus_connection, ev_io *dbusio) dbus_connection_flush(dbus_connection); } +/** Foreword D-Bus process session requests on too the correct function. + * \param w The D-Bus event watcher + * \param revents (not used) + */ static void a_dbus_process_requests_session(EV_P_ ev_io *w, int revents) { a_dbus_process_requests_on_bus(dbus_connection_session, w); } +/** Foreword D-Bus process system requests on too the correct function. + * \param w The D-Bus event watcher + * \param revents (not used) + */ static void a_dbus_process_requests_system(EV_P_ ev_io *w, int revents) { a_dbus_process_requests_on_bus(dbus_connection_system, w); } +/** Attempt to request a D-Bus name + * \param dbus_connection The application's connection to D-Bus + * \param name The D-Bus connection name to be requested + * \return true if the name is primary owner or the name is already + * the owner, otherwise false. + */ static bool a_dbus_request_name(DBusConnection *dbus_connection, const char *name) { @@ -453,6 +483,12 @@ a_dbus_request_name(DBusConnection *dbus_connection, const char *name) return false; } +/** Attempt to release the D-Bus name owner + * \param dbus_connection The application's connection to the D-Bus + * \param name The name to be released + * \return True on success. False if the name is not + * the owner, or does not exist. + */ static bool a_dbus_release_name(DBusConnection *dbus_connection, const char *name) { @@ -484,6 +520,13 @@ a_dbus_release_name(DBusConnection *dbus_connection, const char *name) return true; } +/** Attempt to create a new connection to D-Bus + * \param type The bus type to use when connecting to D-Bus + * \param type_name The bus type name eg: "session" or "system" + * \param dbusio The D-Bus event watcher + * \param cb Function callback to use when processing requests + * \return The requested D-Bus connection on success, NULL on failure. + */ static DBusConnection * a_dbus_connect(DBusBusType type, const char *type_name, ev_io *dbusio, void *cb) @@ -522,6 +565,8 @@ a_dbus_connect(DBusBusType type, const char *type_name, return dbus_connection; } +/** Initialize the D-Bus session and system + */ void a_dbus_init(void) { @@ -531,6 +576,8 @@ a_dbus_init(void) &dbusio_sys, a_dbus_process_requests_system); } +/** Cleanup the D-Bus session and system + */ void a_dbus_cleanup(void) { @@ -538,6 +585,11 @@ a_dbus_cleanup(void) a_dbus_cleanup_bus(dbus_connection_system, &dbusio_sys); } +/** Retrieve the D-Bus bus by it's name + * \param name The name of the bus + * \param len The length of the name variable + * \return The corresponding D-Bus connection + */ static DBusConnection * a_dbus_bus_getbyname(const char *name, size_t len) { @@ -689,13 +741,15 @@ const struct luaL_reg awesome_dbus_lib[] = { NULL, NULL } }; -#else /* HAVE_DBUS */ +#else /* WITH_DBUS */ +/** Empty stub if dbus is not enabled */ void a_dbus_init(void) { } +/** Empty stub if dbus is not enabled */ void a_dbus_cleanup(void) { -- 1.6.3.3
