diff options
31 files changed, 416 insertions, 73 deletions
@@ -1,3 +1,7 @@ +2006-10-19 Havoc Pennington <hp@redhat.com> + + * Fix a pile of Doxygen warnings and missing docs + 2006-10-19 John (J5) Palmieri <johnp@redhat.com> * bus/dir-watch-default.c, bus/dir-watch-dnotify.c, diff --git a/dbus/dbus-address.c b/dbus/dbus-address.c index c6354f14..d92209d9 100644 --- a/dbus/dbus-address.c +++ b/dbus/dbus-address.c @@ -49,8 +49,20 @@ struct DBusAddressEntry }; +/** + * + * Sets #DBUS_ERROR_BAD_ADDRESS. + * If address_problem_type and address_problem_field are not #NULL, + * sets an error message about how the field is no good. Otherwise, sets + * address_problem_other as the error message. + * + * @param error the error to set + * @param address_problem_type the address type of the bad address or #NULL + * @param address_problem_field the missing field of the bad address or #NULL + * @param address_problem_other any other error message or #NULL + */ void -_dbus_set_bad_address (DBusError *error, +_dbus_set_bad_address (DBusError *error, const char *address_problem_type, const char *address_problem_field, const char *address_problem_other) @@ -65,6 +77,10 @@ _dbus_set_bad_address (DBusError *error, address_problem_other); } +/** + * #TRUE if the byte need not be escaped when found in a dbus address. + * All other bytes are required to be escaped in a valid address. + */ #define _DBUS_ADDRESS_OPTIONALLY_ESCAPED_BYTE(b) \ (((b) >= 'a' && (b) <= 'z') || \ ((b) >= 'A' && (b) <= 'Z') || \ @@ -615,6 +631,9 @@ dbus_address_unescape_value (const char *value, /** @} */ /* End of public API */ #ifdef DBUS_BUILD_TESTS + +#ifndef DOXYGEN_SHOULD_SKIP_THIS + #include "dbus-test.h" #include <stdlib.h> @@ -782,4 +801,6 @@ _dbus_address_test (void) return TRUE; } +#endif /* !DOXYGEN_SHOULD_SKIP_THIS */ + #endif diff --git a/dbus/dbus-connection.c b/dbus/dbus-connection.c index 4c1bce91..92fa15a8 100644 --- a/dbus/dbus-connection.c +++ b/dbus/dbus-connection.c @@ -373,18 +373,18 @@ _dbus_connection_queue_received_message (DBusConnection *connection, * variable pointer */ void -_dbus_connection_test_get_locks (DBusConnection *conn, +_dbus_connection_test_get_locks (DBusConnection *connection, DBusMutex **mutex_loc, DBusMutex **dispatch_mutex_loc, DBusMutex **io_path_mutex_loc, DBusCondVar **dispatch_cond_loc, DBusCondVar **io_path_cond_loc) { - *mutex_loc = conn->mutex; - *dispatch_mutex_loc = conn->dispatch_mutex; - *io_path_mutex_loc = conn->io_path_mutex; - *dispatch_cond_loc = conn->dispatch_cond; - *io_path_cond_loc = conn->io_path_cond; + *mutex_loc = connection->mutex; + *dispatch_mutex_loc = connection->dispatch_mutex; + *io_path_mutex_loc = connection->io_path_mutex; + *dispatch_cond_loc = connection->dispatch_cond; + *io_path_cond_loc = connection->io_path_cond; } #endif @@ -578,10 +578,13 @@ _dbus_connection_message_sent (DBusConnection *connection, dbus_message_unref (message); } +/** Function to be called in protected_change_watch() with refcount held */ typedef dbus_bool_t (* DBusWatchAddFunction) (DBusWatchList *list, DBusWatch *watch); +/** Function to be called in protected_change_watch() with refcount held */ typedef void (* DBusWatchRemoveFunction) (DBusWatchList *list, DBusWatch *watch); +/** Function to be called in protected_change_watch() with refcount held */ typedef void (* DBusWatchToggleFunction) (DBusWatchList *list, DBusWatch *watch, dbus_bool_t enabled); @@ -696,10 +699,13 @@ _dbus_connection_toggle_watch_unlocked (DBusConnection *connection, enabled); } +/** Function to be called in protected_change_timeout() with refcount held */ typedef dbus_bool_t (* DBusTimeoutAddFunction) (DBusTimeoutList *list, DBusTimeout *timeout); +/** Function to be called in protected_change_timeout() with refcount held */ typedef void (* DBusTimeoutRemoveFunction) (DBusTimeoutList *list, DBusTimeout *timeout); +/** Function to be called in protected_change_timeout() with refcount held */ typedef void (* DBusTimeoutToggleFunction) (DBusTimeoutList *list, DBusTimeout *timeout, dbus_bool_t enabled); @@ -1736,6 +1742,58 @@ _dbus_connection_open_internal (const char *address, return connection; } +/** + * Closes a shared OR private connection, while dbus_connection_close() can + * only be used on private connections. Should only be called by the + * dbus code that owns the connection - an owner must be known, + * the open/close state is like malloc/free, not like ref/unref. + * + * @param connection the connection + */ +void +_dbus_connection_close_possibly_shared (DBusConnection *connection) +{ + _dbus_assert (connection != NULL); + _dbus_assert (connection->generation == _dbus_current_generation); + + CONNECTION_LOCK (connection); + _dbus_connection_close_possibly_shared_and_unlock (connection); +} + + +/** + * Like dbus_connection_send(), but assumes the connection + * is already locked on function entry, and unlocks before returning. + * + * @param connection the connection + * @param message the message to send + * @param client_serial return location for client serial of sent message + * @returns #FALSE on out-of-memory + */ +dbus_bool_t +_dbus_connection_send_and_unlock (DBusConnection *connection, + DBusMessage *message, + dbus_uint32_t *client_serial) +{ + DBusPreallocatedSend *preallocated; + + _dbus_assert (connection != NULL); + _dbus_assert (message != NULL); + + preallocated = _dbus_connection_preallocate_send_unlocked (connection); + if (preallocated == NULL) + { + CONNECTION_UNLOCK (connection); + return FALSE; + } + + _dbus_connection_send_preallocated_and_unlock (connection, + preallocated, + message, + client_serial); + return TRUE; +} + /** @} */ /** @@ -2062,16 +2120,6 @@ _dbus_connection_close_possibly_shared_and_unlock (DBusConnection *connection) dbus_connection_unref (connection); } -void -_dbus_connection_close_possibly_shared (DBusConnection *connection) -{ - _dbus_assert (connection != NULL); - _dbus_assert (connection->generation == _dbus_current_generation); - - CONNECTION_LOCK (connection); - _dbus_connection_close_possibly_shared_and_unlock (connection); -} - /** * Closes a private connection, so no further data can be sent or received. * This disconnects the transport (such as a socket) underlying the @@ -2505,30 +2553,6 @@ _dbus_connection_send_unlocked_no_update (DBusConnection *connection, return TRUE; } -dbus_bool_t -_dbus_connection_send_and_unlock (DBusConnection *connection, - DBusMessage *message, - dbus_uint32_t *client_serial) -{ - DBusPreallocatedSend *preallocated; - - _dbus_assert (connection != NULL); - _dbus_assert (message != NULL); - - preallocated = _dbus_connection_preallocate_send_unlocked (connection); - if (preallocated == NULL) - { - CONNECTION_UNLOCK (connection); - return FALSE; - } - - _dbus_connection_send_preallocated_and_unlock (connection, - preallocated, - message, - client_serial); - return TRUE; -} - /** * Adds a message to the outgoing message queue. Does not block to * write the message to the network; that happens asynchronously. To @@ -3997,7 +4021,7 @@ _dbus_connection_run_builtin_filters_unlocked_no_update (DBusConnection *connect * unrefs the message. Returns a status indicating whether messages/data * remain, more memory is needed, or all data has been processed. * - * Even if the dispatch status is #DBUS_DISPATCH_DATA_REMAINS, + * Even if the dispatch status is #DBUS_DISPATCH_DATA_REMAINS * does not necessarily dispatch a message, as the data may * be part of authentication or the like. * diff --git a/dbus/dbus-dataslot.c b/dbus/dbus-dataslot.c index 3e9aabfc..a84b9244 100644 --- a/dbus/dbus-dataslot.c +++ b/dbus/dbus-dataslot.c @@ -151,7 +151,7 @@ _dbus_data_slot_allocator_alloc (DBusDataSlotAllocator *allocator, /** * Deallocates an ID previously allocated with * _dbus_data_slot_allocator_alloc(). Existing data stored on - * existing #DBusDataList objects with this ID will be freed when the + * existing #DBusDataSlotList objects with this ID will be freed when the * data list is finalized, but may not be retrieved (and may only be * replaced if someone else reallocates the slot). * The slot value is reset to -1 if this is the last unref. diff --git a/dbus/dbus-hash.h b/dbus/dbus-hash.h index 0d1e322b..4424e8c8 100644 --- a/dbus/dbus-hash.h +++ b/dbus/dbus-hash.h @@ -58,6 +58,7 @@ typedef enum DBUS_HASH_POINTER, /**< Hash keys are pointers. */ DBUS_HASH_ULONG /**< Hash keys are unsigned long. */ } DBusHashType; + DBusHashTable* _dbus_hash_table_new (DBusHashType type, DBusFreeFunction key_free_function, DBusFreeFunction value_free_function); diff --git a/dbus/dbus-internals.c b/dbus/dbus-internals.c index 2233fc68..5268ebdf 100644 --- a/dbus/dbus-internals.c +++ b/dbus/dbus-internals.c @@ -28,8 +28,12 @@ #include <string.h> #include <stdlib.h> +/* the blurb for this is "D-Bus secret" so it comes after "D-Bus low-level" + * which is the blurb for the DBus group, which makes Doxygen show + * the public API first on the index page. Yay for lame hacks. + */ /** - * @defgroup DBusInternals D-Bus internal implementation details + * @defgroup DBusInternals D-Bus secret internal implementation details * @brief Documentation useful when developing or debugging D-Bus itself. * */ @@ -288,6 +292,7 @@ _dbus_warn_check_failed(const char *format, static dbus_bool_t verbose_initted = FALSE; static dbus_bool_t verbose = TRUE; +/** Whether to show the current thread in verbose messages */ #define PTHREAD_IN_VERBOSE 0 #if PTHREAD_IN_VERBOSE #include <pthread.h> @@ -304,6 +309,11 @@ _dbus_verbose_init (void) } } +/** + * Implementation of dbus_is_verbose() macro if built with verbose logging + * enabled. + * @returns whether verbose logging is active. + */ dbus_bool_t _dbus_is_verbose_real (void) { diff --git a/dbus/dbus-internals.h b/dbus/dbus-internals.h index 3c8750e9..c0422c83 100644 --- a/dbus/dbus-internals.h +++ b/dbus/dbus-internals.h @@ -322,8 +322,8 @@ void _dbus_set_bad_address (DBusError *error, */ union DBusGUID { - dbus_uint32_t as_uint32s[DBUS_UUID_LENGTH_BYTES / 4]; - char as_bytes[DBUS_UUID_LENGTH_BYTES]; + dbus_uint32_t as_uint32s[DBUS_UUID_LENGTH_BYTES / 4]; /**< guid as four uint32 values */ + char as_bytes[DBUS_UUID_LENGTH_BYTES]; /**< guid as 16 single-byte values */ }; void _dbus_generate_uuid (DBusGUID *uuid); diff --git a/dbus/dbus-mainloop.c b/dbus/dbus-mainloop.c index b3089bbc..68284474 100644 --- a/dbus/dbus-mainloop.c +++ b/dbus/dbus-mainloop.c @@ -905,4 +905,4 @@ _dbus_wait_for_memory (void) _dbus_sleep_milliseconds (_dbus_get_oom_wait ()); } -#endif /* DOXYGEN_SHOULD_SKIP_THIS */ +#endif /* !DOXYGEN_SHOULD_SKIP_THIS */ diff --git a/dbus/dbus-mainloop.h b/dbus/dbus-mainloop.h index cc23129b..52bcd8fc 100644 --- a/dbus/dbus-mainloop.h +++ b/dbus/dbus-mainloop.h @@ -70,7 +70,7 @@ dbus_bool_t _dbus_loop_dispatch (DBusLoop *loop); int _dbus_get_oom_wait (void); void _dbus_wait_for_memory (void); -#endif /* DOXYGEN_SHOULD_SKIP_THIS */ +#endif /* !DOXYGEN_SHOULD_SKIP_THIS */ #endif /* DBUS_MAINLOOP_H */ diff --git a/dbus/dbus-marshal-header.c b/dbus/dbus-marshal-header.c index 6df8605b..564e47b5 100644 --- a/dbus/dbus-marshal-header.c +++ b/dbus/dbus-marshal-header.c @@ -67,8 +67,8 @@ _DBUS_STRING_DEFINE_STATIC(_dbus_local_path_str, DBUS_PATH_LOCAL); typedef struct { - unsigned char code; - unsigned char type; + unsigned char code; /**< the field code */ + unsigned char type; /**< the value type */ } HeaderFieldType; static const HeaderFieldType diff --git a/dbus/dbus-marshal-recursive-util.c b/dbus/dbus-marshal-recursive-util.c index e73edf49..3d4320d9 100644 --- a/dbus/dbus-marshal-recursive-util.c +++ b/dbus/dbus-marshal-recursive-util.c @@ -124,6 +124,9 @@ _dbus_type_reader_equal_values (const DBusTypeReader *lhs, } /* TESTS */ + +#ifndef DOXYGEN_SHOULD_SKIP_THIS + #include "dbus-test.h" #include "dbus-list.h" #include <stdio.h> @@ -3557,4 +3560,6 @@ container_destroy (TestTypeNode *node) } } +#endif /* !DOXYGEN_SHOULD_SKIP_THIS */ + #endif /* DBUS_BUILD_TESTS */ diff --git a/dbus/dbus-marshal-recursive.c b/dbus/dbus-marshal-recursive.c index 536d4cbf..501e9a53 100644 --- a/dbus/dbus-marshal-recursive.c +++ b/dbus/dbus-marshal-recursive.c @@ -1116,8 +1116,8 @@ _dbus_type_reader_get_signature (const DBusTypeReader *reader, typedef struct { - DBusString replacement; - int padding; + DBusString replacement; /**< Marshaled value including alignment padding */ + int padding; /**< How much of the replacement block is padding */ } ReplacementBlock; static dbus_bool_t diff --git a/dbus/dbus-marshal-validate-util.c b/dbus/dbus-marshal-validate-util.c index d9beee6c..341b2762 100644 --- a/dbus/dbus-marshal-validate-util.c +++ b/dbus/dbus-marshal-validate-util.c @@ -23,6 +23,9 @@ #include <config.h> #ifdef DBUS_BUILD_TESTS + +#ifndef DOXYGEN_SHOULD_SKIP_THIS + #include "dbus-internals.h" #include "dbus-marshal-validate.h" #include "dbus-marshal-recursive.h" @@ -579,4 +582,6 @@ _dbus_marshal_validate_test (void) return TRUE; } +#endif /* !DOXYGEN_SHOULD_SKIP_THIS */ + #endif /* DBUS_BUILD_TESTS */ diff --git a/dbus/dbus-md5.c b/dbus/dbus-md5.c index 079b1cc0..b7ddb5f4 100644 --- a/dbus/dbus-md5.c +++ b/dbus/dbus-md5.c @@ -157,7 +157,7 @@ main(int argc, char **argv) #define T62 /* 0xbd3af235 */ (T_MASK ^ 0x42c50dca) #define T63 0x2ad7d2bb #define T64 /* 0xeb86d391 */ (T_MASK ^ 0x14792c6e) -#endif /* DOXYGEN_SHOULD_SKIP_THIS */ +#endif /* !DOXYGEN_SHOULD_SKIP_THIS */ static void md5_process(DBusMD5Context *context, const unsigned char *data /*[64]*/) diff --git a/dbus/dbus-message-factory.c b/dbus/dbus-message-factory.c index c3fb1bc1..db1b254d 100644 --- a/dbus/dbus-message-factory.c +++ b/dbus/dbus-message-factory.c @@ -22,6 +22,8 @@ */ #include <config.h> +#ifndef DOXYGEN_SHOULD_SKIP_THIS + #ifdef DBUS_BUILD_TESTS #include "dbus-message-factory.h" #include "dbus-message-private.h" @@ -1221,4 +1223,6 @@ _dbus_message_data_iter_get_and_next (DBusMessageDataIter *iter, return TRUE; } +#endif /* !DOXYGEN_SHOULD_SKIP_THIS */ + #endif /* DBUS_BUILD_TESTS */ diff --git a/dbus/dbus-message.c b/dbus/dbus-message.c index 9b0d7a0b..80eee1cb 100644 --- a/dbus/dbus-message.c +++ b/dbus/dbus-message.c @@ -126,6 +126,12 @@ _dbus_message_byteswap (DBusMessage *message) _dbus_header_byteswap (&message->header, DBUS_COMPILER_BYTE_ORDER); } +/** byte-swap the message if it doesn't match our byte order. + * Called only when we need the message in our own byte order, + * normally when reading arrays of integers or doubles. + * Otherwise should not be called since it would do needless + * work. + */ #define ensure_byte_order(message) \ if (message->byte_order != DBUS_COMPILER_BYTE_ORDER) \ _dbus_message_byteswap (message) @@ -1119,10 +1125,9 @@ dbus_message_unref (DBusMessage *message) * #DBUS_MESSAGE_TYPE_METHOD_CALL, #DBUS_MESSAGE_TYPE_METHOD_RETURN, * #DBUS_MESSAGE_TYPE_ERROR, #DBUS_MESSAGE_TYPE_SIGNAL, but other * types are allowed and all code must silently ignore messages of - * unknown type. DBUS_MESSAGE_TYPE_INVALID will never be returned, + * unknown type. #DBUS_MESSAGE_TYPE_INVALID will never be returned, * however. * - * * @param message the message * @returns the type of the message */ diff --git a/dbus/dbus-object-tree.c b/dbus/dbus-object-tree.c index ec83498b..e5ff7734 100644 --- a/dbus/dbus-object-tree.c +++ b/dbus/dbus-object-tree.c @@ -1141,6 +1141,9 @@ _dbus_decompose_path (const char* data, /** @} */ #ifdef DBUS_BUILD_TESTS + +#ifndef DOXYGEN_SHOULD_SKIP_THIS + #include "dbus-test.h" #include <stdio.h> @@ -1926,4 +1929,6 @@ _dbus_object_tree_test (void) return TRUE; } +#endif /* !DOXYGEN_SHOULD_SKIP_THIS */ + #endif /* DBUS_BUILD_TESTS */ diff --git a/dbus/dbus-pending-call.c b/dbus/dbus-pending-call.c index ec57395e..79dacc8a 100644 --- a/dbus/dbus-pending-call.c +++ b/dbus/dbus-pending-call.c @@ -44,7 +44,14 @@ * * Opaque object representing a reply message that we're waiting for. */ + +/** + * shorter and more visible way to write _dbus_connection_lock() + */ #define CONNECTION_LOCK(connection) _dbus_connection_lock(connection) +/** + * shorter and more visible way to write _dbus_connection_unlock() + */ #define CONNECTION_UNLOCK(connection) _dbus_connection_unlock(connection) struct DBusPendingCall @@ -189,6 +196,13 @@ _dbus_pending_call_complete (DBusPendingCall *pending) } } +/** + * If the pending call hasn't been timed out, add its timeout + * error reply to the connection's incoming message queue. + * + * @param pending the pending call + * @param connection the connection the call was sent to + */ void _dbus_pending_call_queue_timeout_error_unlocked (DBusPendingCall *pending, DBusConnection *connection) diff --git a/dbus/dbus-protocol.h b/dbus/dbus-protocol.h index 4cfb6d16..a36e67c3 100644 --- a/dbus/dbus-protocol.h +++ b/dbus/dbus-protocol.h @@ -31,6 +31,9 @@ #ifdef __cplusplus extern "C" { +#if 0 +} /* avoids confusing emacs indentation */ +#endif #endif /* Normally docs are in .c files, but there isn't a .c file for this. */ @@ -52,62 +55,113 @@ extern "C" { /** Protocol version */ #define DBUS_MAJOR_PROTOCOL_VERSION 1 -/** Never a legitimate type */ +/** Type code that is never equal to a legitimate type code */ #define DBUS_TYPE_INVALID ((int) '\0') +/** #DBUS_TYPE_INVALID as a string literal instead of a int literal */ #define DBUS_TYPE_INVALID_AS_STRING "\0" /* Primitive types */ +/** Type code marking an 8-bit unsigned integer */ #define DBUS_TYPE_BYTE ((int) 'y') +/** #DBUS_TYPE_BYTE as a string literal instead of a int literal */ #define DBUS_TYPE_BYTE_AS_STRING "y" +/** Type code marking a boolean */ #define DBUS_TYPE_BOOLEAN ((int) 'b') +/** #DBUS_TYPE_BOOLEAN as a string literal instead of a int literal */ #define DBUS_TYPE_BOOLEAN_AS_STRING "b" +/** Type code marking a 16-bit signed integer */ #define DBUS_TYPE_INT16 ((int) 'n') +/** #DBUS_TYPE_INT16 as a string literal instead of a int literal */ #define DBUS_TYPE_INT16_AS_STRING "n" +/** Type code marking a 16-bit unsigned integer */ #define DBUS_TYPE_UINT16 ((int) 'q') +/** #DBUS_TYPE_UINT16 as a string literal instead of a int literal */ #define DBUS_TYPE_UINT16_AS_STRING "q" +/** Type code marking a 32-bit signed integer */ #define DBUS_TYPE_INT32 ((int) 'i') +/** #DBUS_TYPE_INT32 as a string literal instead of a int literal */ #define DBUS_TYPE_INT32_AS_STRING "i" +/** Type code marking a 32-bit unsigned integer */ #define DBUS_TYPE_UINT32 ((int) 'u') +/** #DBUS_TYPE_UINT32 as a string literal instead of a int literal */ #define DBUS_TYPE_UINT32_AS_STRING "u" +/** Type code marking a 64-bit signed integer */ #define DBUS_TYPE_INT64 ((int) 'x') +/** #DBUS_TYPE_INT64 as a string literal instead of a int literal */ #define DBUS_TYPE_INT64_AS_STRING "x" +/** Type code marking a 64-bit unsigned integer */ #define DBUS_TYPE_UINT64 ((int) 't') +/** #DBUS_TYPE_UINT64 as a string literal instead of a int literal */ #define DBUS_TYPE_UINT64_AS_STRING "t" +/** Type code marking an 8-byte double in IEEE 754 format */ #define DBUS_TYPE_DOUBLE ((int) 'd') +/** #DBUS_TYPE_DOUBLE as a string literal instead of a int literal */ #define DBUS_TYPE_DOUBLE_AS_STRING "d" +/** Type code marking a UTF-8 encoded, nul-terminated Unicode string */ #define DBUS_TYPE_STRING ((int) 's') +/** #DBUS_TYPE_STRING as a string literal instead of a int literal */ #define DBUS_TYPE_STRING_AS_STRING "s" +/** Type code marking a D-Bus object path */ #define DBUS_TYPE_OBJECT_PATH ((int) 'o') +/** #DBUS_TYPE_OBJECT_PATH as a string literal instead of a int literal */ #define DBUS_TYPE_OBJECT_PATH_AS_STRING "o" +/** Type code marking a D-Bus type signature */ #define DBUS_TYPE_SIGNATURE ((int) 'g') +/** #DBUS_TYPE_SIGNATURE as a string literal instead of a int literal */ #define DBUS_TYPE_SIGNATURE_AS_STRING "g" /* Compound types */ +/** Type code marking a D-Bus array type */ #define DBUS_TYPE_ARRAY ((int) 'a') +/** #DBUS_TYPE_ARRAY as a string literal instead of a int literal */ #define DBUS_TYPE_ARRAY_AS_STRING "a" +/** Type code marking a D-Bus variant type */ #define DBUS_TYPE_VARIANT ((int) 'v') +/** #DBUS_TYPE_VARIANT as a string literal instead of a int literal */ #define DBUS_TYPE_VARIANT_AS_STRING "v" /** STRUCT and DICT_ENTRY are sort of special since their codes can't * appear in a type string, instead * DBUS_STRUCT_BEGIN_CHAR/DBUS_DICT_ENTRY_BEGIN_CHAR have to appear */ +/** Type code used to represent a struct; however, this type code does not appear + * in type signatures, instead #DBUS_STRUCT_BEGIN_CHAR and #DBUS_STRUCT_END_CHAR will + * appear in a signature. + */ #define DBUS_TYPE_STRUCT ((int) 'r') +/** #DBUS_TYPE_STRUCT as a string literal instead of a int literal */ #define DBUS_TYPE_STRUCT_AS_STRING "r" +/** Type code used to represent a dict entry; however, this type code does not appear + * in type signatures, instead #DBUS_DICT_ENTRY_BEGIN_CHAR and #DBUS_DICT_ENTRY_END_CHAR will + * appear in a signature. + */ #define DBUS_TYPE_DICT_ENTRY ((int) 'e') +/** #DBUS_TYPE_DICT_ENTRY as a string literal instead of a int literal */ #define DBUS_TYPE_DICT_ENTRY_AS_STRING "e" -/** Does not count INVALID */ +/** Does not include #DBUS_TYPE_INVALID, #DBUS_STRUCT_BEGIN_CHAR, #DBUS_STRUCT_END_CHAR, + * #DBUS_DICT_ENTRY_BEGIN_CHAR, or #DBUS_DICT_ENTRY_END_CHAR - i.e. it is the number of + * valid types, not the number of distinct characters that may appear in a type signature. + */ #define DBUS_NUMBER_OF_TYPES (16) /* characters other than typecodes that appear in type signatures */ + +/** Code marking the start of a struct type in a type signature */ #define DBUS_STRUCT_BEGIN_CHAR ((int) '(') +/** #DBUS_STRUCT_BEGIN_CHAR as a string literal instead of a int literal */ #define DBUS_STRUCT_BEGIN_CHAR_AS_STRING "(" +/** Code marking the end of a struct type in a type signature */ #define DBUS_STRUCT_END_CHAR ((int) ')') +/** #DBUS_STRUCT_END_CHAR a string literal instead of a int literal */ #define DBUS_STRUCT_END_CHAR_AS_STRING ")" +/** Code marking the start of a dict entry type in a type signature */ #define DBUS_DICT_ENTRY_BEGIN_CHAR ((int) '{') +/** #DBUS_DICT_ENTRY_BEGIN_CHAR as a string literal instead of a int literal */ #define DBUS_DICT_ENTRY_BEGIN_CHAR_AS_STRING "{" +/** Code marking the end of a dict entry type in a type signature */ #define DBUS_DICT_ENTRY_END_CHAR ((int) '}') +/** #DBUS_DICT_ENTRY_END_CHAR as a string literal instead of a int literal */ #define DBUS_DICT_ENTRY_END_CHAR_AS_STRING "}" /** Max length in bytes of a bus name, interface, or member (not object @@ -160,27 +214,74 @@ extern "C" { #define DBUS_MAXIMUM_TYPE_RECURSION_DEPTH 32 /* Types of message */ + +/** This value is never a valid message type, see dbus_message_get_type() */ #define DBUS_MESSAGE_TYPE_INVALID 0 +/** Message type of a method call message, see dbus_message_get_type() */ #define DBUS_MESSAGE_TYPE_METHOD_CALL 1 +/** Message type of a method return message, see dbus_message_get_type() */ #define DBUS_MESSAGE_TYPE_METHOD_RETURN 2 +/** Message type of an error reply message, see dbus_message_get_type() */ #define DBUS_MESSAGE_TYPE_ERROR 3 +/** Message type of a signal message, see dbus_message_get_type() */ #define DBUS_MESSAGE_TYPE_SIGNAL 4 /* Header flags */ + +/** If set, this flag means that the sender of a message does not care about getting + * a reply, so the recipient need not send one. See dbus_message_set_no_reply(). + */ #define DBUS_HEADER_FLAG_NO_REPLY_EXPECTED 0x1 +/** + * If set, this flag means that even if the message bus knows how to start an owner for + * the destination bus name (see dbus_message_set_destination()), it should not + * do so. If this flag is not set, the bus may launch a program to process the + * message. + */ #define DBUS_HEADER_FLAG_NO_AUTO_START 0x2 /* Header fields */ + +/** Not equal to any valid header field code */ #define DBUS_HEADER_FIELD_INVALID 0 +/** Header field code for the path - the path is the object emitting a signal or the object receiving a method call. + * See dbus_message_set_path(). + */ #define DBUS_HEADER_FIELD_PATH 1 +/** Header field code for the interface containing a member (method or signal). + * See dbus_message_set_interface(). + */ #define DBUS_HEADER_FIELD_INTERFACE 2 +/** Header field code for a member (method or signal). See dbus_message_set_member(). */ #define DBUS_HEADER_FIELD_MEMBER 3 +/** Header field code for an error name (found in #DBUS_MESSAGE_TYPE_ERROR messages). + * See dbus_message_set_error_name(). + */ #define DBUS_HEADER_FIELD_ERROR_NAME 4 +/** Header field code for a reply serial, used to match a #DBUS_MESSAGE_TYPE_METHOD_RETURN message with the + * message that it's a reply to. See dbus_message_set_reply_serial(). + */ #define DBUS_HEADER_FIELD_REPLY_SERIAL 5 +/** + * Header field code for the destination bus name of a message. See dbus_message_set_destination(). + */ #define DBUS_HEADER_FIELD_DESTINATION 6 +/** + * Header field code for the sender of a message; usually initialized by the message bus. + * See dbus_message_set_sender(). + */ #define DBUS_HEADER_FIELD_SENDER 7 +/** + * Header field code for the type signature of a message. + */ #define DBUS_HEADER_FIELD_SIGNATURE 8 +/** + * Value of the highest-numbered header field code, can be used to determine + * the size of an array indexed by header field code. Remember though + * that unknown codes must be ignored, so check for that before + * indexing the array. + */ #define DBUS_HEADER_FIELD_LAST DBUS_HEADER_FIELD_SIGNATURE /** Header format is defined as a signature: @@ -224,47 +325,88 @@ extern "C" { * Also, don't change the formatting since that will break the sed * script. */ +/** A generic error; "something went wrong" - see the error message for more. */ #define DBUS_ERROR_FAILED "org.freedesktop.DBus.Error.Failed" +/** There was not enough memory to complete an operation. */ #define DBUS_ERROR_NO_MEMORY "org.freedesktop.DBus.Error.NoMemory" +/** The bus doesn't know how to launch a service to supply the bus name you wanted. */ #define DBUS_ERROR_SERVICE_UNKNOWN "org.freedesktop.DBus.Error.ServiceUnknown" +/** The bus name you referenced doesn't exist (i.e. no application owns it). */ #define DBUS_ERROR_NAME_HAS_NO_OWNER "org.freedesktop.DBus.Error.NameHasNoOwner" +/** No reply to a message expecting one, usually means a timeout occurred. */ #define DBUS_ERROR_NO_REPLY "org.freedesktop.DBus.Error.NoReply" +/** Something went wrong reading or writing to a socket, for example. */ #define DBUS_ERROR_IO_ERROR "org.freedesktop.DBus.Error.IOError" +/** A D-Bus bus address was malformed. */ #define DBUS_ERROR_BAD_ADDRESS "org.freedesktop.DBus.Error.BadAddress" +/** Requested operation isn't supported (like ENOSYS on UNIX). */ #define DBUS_ERROR_NOT_SUPPORTED "org.freedesktop.DBus.Error.NotSupported" +/** Some limited resource is exhausted. */ #define DBUS_ERROR_LIMITS_EXCEEDED "org.freedesktop.DBus.Error.LimitsExceeded" +/** Security restrictions don't allow doing what you're trying to do. */ #define DBUS_ERROR_ACCESS_DENIED "org.freedesktop.DBus.Error.AccessDenied" +/** Authentication didn't work. */ #define DBUS_ERROR_AUTH_FAILED "org.freedesktop.DBus.Error.AuthFailed" +/** Unable to connect to server (probably caused by ECONNREFUSED on a socket). */ #define DBUS_ERROR_NO_SERVER "org.freedesktop.DBus.Error.NoServer" +/** Certain timeout errors, possibly ETIMEDOUT on a socket. Note that #DBUS_ERROR_NO_REPLY is used for message reply timeouts. */ #define DBUS_ERROR_TIMEOUT "org.freedesktop.DBus.Error.Timeout" +/** No network access (probably ENETUNREACH on a socket). */ #define DBUS_ERROR_NO_NETWORK "org.freedesktop.DBus.Error.NoNetwork" +/** Can't bind a socket since its address is in use (i.e. EADDRINUSE). */ #define DBUS_ERROR_ADDRESS_IN_USE "org.freedesktop.DBus.Error.AddressInUse" +/** The connection is disconnected and you're trying to use it. */ #define DBUS_ERROR_DISCONNECTED "org.freedesktop.DBus.Error.Disconnected" +/** Invalid arguments passed to a method call. */ #define DBUS_ERROR_INVALID_ARGS "org.freedesktop.DBus.Error.InvalidArgs" +/** Missing file. */ #define DBUS_ERROR_FILE_NOT_FOUND "org.freedesktop.DBus.Error.FileNotFound" +/** Existing file and the operation you're using does not silently overwrite. */ #define DBUS_ERROR_FILE_EXISTS "org.freedesktop.DBus.Error.FileExists" +/** Method name you invoked isn't known by the object you invoked it on. */ #define DBUS_ERROR_UNKNOWN_METHOD "org.freedesktop.DBus.Error.UnknownMethod" +/** Certain other timeout errors, e.g. while starting a service. @todo redundant with #DBUS_ERROR_TIMEOUT */ #define DBUS_ERROR_TIMED_OUT "org.freedesktop.DBus.Error.TimedOut" +/** Tried to remove or modify a match rule that didn't exist. */ #define DBUS_ERROR_MATCH_RULE_NOT_FOUND "org.freedesktop.DBus.Error.MatchRuleNotFound" +/** The match rule isn't syntactically valid. */ #define DBUS_ERROR_MATCH_RULE_INVALID "org.freedesktop.DBus.Error.MatchRuleInvalid" +/** While starting a new process, the exec() call failed. */ #define DBUS_ERROR_SPAWN_EXEC_FAILED "org.freedesktop.DBus.Error.Spawn.ExecFailed" +/** While starting a new process, the fork() call failed. */ #define DBUS_ERROR_SPAWN_FORK_FAILED "org.freedesktop.DBus.Error.Spawn.ForkFailed" +/** While starting a new process, the child exited with a status code. */ #define DBUS_ERROR_SPAWN_CHILD_EXITED "org.freedesktop.DBus.Error.Spawn.ChildExited" +/** While starting a new process, the child exited on a signal. */ #define DBUS_ERROR_SPAWN_CHILD_SIGNALED "org.freedesktop.DBus.Error.Spawn.ChildSignaled" +/** While starting a new process, something went wrong. */ #define DBUS_ERROR_SPAWN_FAILED "org.freedesktop.DBus.Error.Spawn.Failed" +/** Tried to get a UNIX process ID and it wasn't available. */ #define DBUS_ERROR_UNIX_PROCESS_ID_UNKNOWN "org.freedesktop.DBus.Error.UnixProcessIdUnknown" +/** A type signature is not valid. */ #define DBUS_ERROR_INVALID_SIGNATURE "org.freedesktop.DBus.Error.InvalidSignature" +/** A file contains invalid syntax or is otherwise broken. */ #define DBUS_ERROR_INVALID_FILE_CONTENT "org.freedesktop.DBus.Error.InvalidFileContent" +/** Asked for SELinux security context and it wasn't available. */ #define DBUS_ERROR_SELINUX_SECURITY_CONTEXT_UNKNOWN "org.freedesktop.DBus.Error.SELinuxSecurityContextUnknown" +/* XML introspection format */ + +/** XML namespace of the introspection format version 1.0 */ #define DBUS_INTROSPECT_1_0_XML_NAMESPACE "http://www.freedesktop.org/standards/dbus" +/** XML public identifier of the introspection format version 1.0 */ #define DBUS_INTROSPECT_1_0_XML_PUBLIC_IDENTIFIER "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" +/** XML system identifier of the introspection format version 1.0 */ #define DBUS_INTROSPECT_1_0_XML_SYSTEM_IDENTIFIER "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd" +/** XML document type declaration of the introspection format version 1.0 */ #define DBUS_INTROSPECT_1_0_XML_DOCTYPE_DECL_NODE "<!DOCTYPE node PUBLIC \""DBUS_INTROSPECT_1_0_XML_PUBLIC_IDENTIFIER"\"\n\""DBUS_INTROSPECT_1_0_XML_SYSTEM_IDENTIFIER"\">\n" /** @} */ #ifdef __cplusplus +#if 0 +{ /* avoids confusing emacs indentation */ +#endif } #endif diff --git a/dbus/dbus-server-debug-pipe.c b/dbus/dbus-server-debug-pipe.c index 0fb45c63..27115caa 100644 --- a/dbus/dbus-server-debug-pipe.c +++ b/dbus/dbus-server-debug-pipe.c @@ -329,7 +329,7 @@ _dbus_transport_debug_pipe_new (const char *server_name, * Sets error if the result is not OK. * * @param entry an address entry - * @param a new DBusServer, or #NULL on failure. + * @param server_p location to store a new DBusServer, or #NULL on failure. * @param error location to store rationale for failure on bad address * @returns the outcome * @@ -376,6 +376,14 @@ _dbus_server_listen_debug_pipe (DBusAddressEntry *entry, } } +/** + * Opens a debug pipe transport, used in the test suite. + * + * @param entry the address entry to try opening as debug-pipe + * @param transport_p return location for the opened transport + * @param error error to be set + * @returns result of the attempt + */ DBusTransportOpenResult _dbus_transport_open_debug_pipe (DBusAddressEntry *entry, DBusTransport **transport_p, diff --git a/dbus/dbus-server-unix.c b/dbus/dbus-server-unix.c index ffc68709..6dd28bcf 100644 --- a/dbus/dbus-server-unix.c +++ b/dbus/dbus-server-unix.c @@ -43,7 +43,7 @@ * Sets error if the result is not OK. * * @param entry an address entry - * @param a new DBusServer, or #NULL on failure. + * @param server_p location to store a new DBusServer, or #NULL on failure. * @param error location to store rationale for failure on bad address * @returns the outcome * diff --git a/dbus/dbus-server.c b/dbus/dbus-server.c index 059c8485..b54133bb 100644 --- a/dbus/dbus-server.c +++ b/dbus/dbus-server.c @@ -194,10 +194,13 @@ _dbus_server_finalize_base (DBusServer *server) } +/** Function to be called in protected_change_watch() with refcount held */ typedef dbus_bool_t (* DBusWatchAddFunction) (DBusWatchList *list, DBusWatch *watch); +/** Function to be called in protected_change_watch() with refcount held */ typedef void (* DBusWatchRemoveFunction) (DBusWatchList *list, DBusWatch *watch); +/** Function to be called in protected_change_watch() with refcount held */ typedef void (* DBusWatchToggleFunction) (DBusWatchList *list, DBusWatch *watch, dbus_bool_t enabled); @@ -307,11 +310,13 @@ _dbus_server_toggle_watch (DBusServer *server, enabled); } - +/** Function to be called in protected_change_timeout() with refcount held */ typedef dbus_bool_t (* DBusTimeoutAddFunction) (DBusTimeoutList *list, DBusTimeout *timeout); +/** Function to be called in protected_change_timeout() with refcount held */ typedef void (* DBusTimeoutRemoveFunction) (DBusTimeoutList *list, DBusTimeout *timeout); +/** Function to be called in protected_change_timeout() with refcount held */ typedef void (* DBusTimeoutToggleFunction) (DBusTimeoutList *list, DBusTimeout *timeout, dbus_bool_t enabled); diff --git a/dbus/dbus-sha.c b/dbus/dbus-sha.c index b386e452..4a5b8d18 100644 --- a/dbus/dbus-sha.c +++ b/dbus/dbus-sha.c @@ -157,7 +157,7 @@ effort (for example the reengineering of a great many Capstone chips). #define subRound(a, b, c, d, e, f, k, data) \ ( e += ROTL( 5, a ) + f( b, c, d ) + k + data, b = ROTL( 30, b ) ) -#endif /* DOXYGEN_SHOULD_SKIP_THIS */ +#endif /* !DOXYGEN_SHOULD_SKIP_THIS */ /* Perform the SHA transformation. Note that this code, like MD5, seems to break some optimizing compilers due to the complexity of the expressions diff --git a/dbus/dbus-shared.h b/dbus/dbus-shared.h index 357327da..78d305ef 100644 --- a/dbus/dbus-shared.h +++ b/dbus/dbus-shared.h @@ -30,6 +30,9 @@ #ifdef __cplusplus extern "C" { +#if 0 +} /* avoids confusing emacs indentation */ +#endif #endif /* Normally docs are in .c files, but there isn't a .c file for this. */ @@ -44,6 +47,9 @@ extern "C" { */ +/** + * Well-known bus types. See dbus_bus_get(). + */ typedef enum { DBUS_BUS_SESSION, /**< The login session bus */ @@ -51,26 +57,37 @@ typedef enum DBUS_BUS_STARTER /**< The bus that started us, if any */ } DBusBusType; +/** + * Results that a message handler can return. + */ typedef enum { - DBUS_HANDLER_RESULT_HANDLED, /**< Message has had its effect */ - DBUS_HANDLER_RESULT_NOT_YET_HANDLED, /**< Message has not had any effect */ - DBUS_HANDLER_RESULT_NEED_MEMORY /**< Need more memory to return another result */ + DBUS_HANDLER_RESULT_HANDLED, /**< Message has had its effect - no need to run more handlers. */ + DBUS_HANDLER_RESULT_NOT_YET_HANDLED, /**< Message has not had any effect - see if other handlers want it. */ + DBUS_HANDLER_RESULT_NEED_MEMORY /**< Need more memory in order to return #DBUS_HANDLER_RESULT_HANDLED or #DBUS_HANDLER_RESULT_NOT_YET_HANDLED. Please try again later with more memory. */ } DBusHandlerResult; -/* Services */ +/* Bus names */ + +/** The bus name used to talk to the bus itself. */ #define DBUS_SERVICE_DBUS "org.freedesktop.DBus" /* Paths */ +/** The object path used to talk to the bus itself. */ #define DBUS_PATH_DBUS "/org/freedesktop/DBus" +/** The object path used in local/in-process-generated messages. */ #define DBUS_PATH_LOCAL "/org/freedesktop/DBus/Local" /* Interfaces, these #define don't do much other than * catch typos at compile time */ +/** The interface exported by the object with #DBUS_SERVICE_DBUS and #DBUS_PATH_DBUS */ #define DBUS_INTERFACE_DBUS "org.freedesktop.DBus" +/** The interface supported by introspectable objects */ #define DBUS_INTERFACE_INTROSPECTABLE "org.freedesktop.DBus.Introspectable" +/** The interface supported by objects with properties */ #define DBUS_INTERFACE_PROPERTIES "org.freedesktop.DBus.Properties" +/** The interface supported by most dbus peers */ #define DBUS_INTERFACE_PEER "org.freedesktop.DBus.Peer" /** This is a special interface whose methods can only be invoked @@ -102,6 +119,9 @@ typedef enum /** @} */ #ifdef __cplusplus +#if 0 +{ /* avoids confusing emacs indentation */ +#endif } #endif diff --git a/dbus/dbus-signature.c b/dbus/dbus-signature.c index 2852ed4d..5ac1afa1 100644 --- a/dbus/dbus-signature.c +++ b/dbus/dbus-signature.c @@ -29,9 +29,9 @@ typedef struct { - const char *pos; - unsigned int finished : 1; - unsigned int in_array : 1; + const char *pos; /**< current position in the signature string */ + unsigned int finished : 1; /**< true if we are at the end iter */ + unsigned int in_array : 1; /**< true if we are a subiterator pointing to an array's element type */ } DBusSignatureRealIter; /** diff --git a/dbus/dbus-string.c b/dbus/dbus-string.c index 86cb986f..bfacb24e 100644 --- a/dbus/dbus-string.c +++ b/dbus/dbus-string.c @@ -2011,7 +2011,7 @@ _dbus_string_skip_white_reverse (const DBusString *str, * @todo owen correctly notes that this is a stupid function (it was * written purely for test code, * e.g. dbus-message-builder.c). Probably should be enforced as test - * code only with #ifdef DBUS_BUILD_TESTS + * code only with ifdef DBUS_BUILD_TESTS * * @param source the source string * @param dest the destination string (contents are replaced) diff --git a/dbus/dbus-sysdeps-unix.c b/dbus/dbus-sysdeps-unix.c index aa0de381..c8a349cc 100644 --- a/dbus/dbus-sysdeps-unix.c +++ b/dbus/dbus-sysdeps-unix.c @@ -107,6 +107,13 @@ _dbus_open_tcp_socket (int *fd, return _dbus_open_socket(fd, AF_INET, SOCK_STREAM, 0, error); } +/** + * Opens a UNIX domain socket (as in the socket() call). + * Does not bind the socket. + * @param fd return location for socket descriptor + * @param error return location for an error + * @returns #FALSE if error is set + */ dbus_bool_t _dbus_open_unix_socket (int *fd, DBusError *error) @@ -114,6 +121,14 @@ _dbus_open_unix_socket (int *fd, return _dbus_open_socket(fd, PF_UNIX, SOCK_STREAM, 0, error); } +/** + * Closes a socket. Should not be used on non-socket + * file descriptors or handles. + * + * @param fd the socket + * @param error return location for an error + * @returns #FALSE if error is set + */ dbus_bool_t _dbus_close_socket (int fd, DBusError *error) @@ -121,6 +136,15 @@ _dbus_close_socket (int fd, return _dbus_close (fd, error); } +/** + * Like _dbus_read(), but only works on sockets so is + * available on Windows. + * + * @param fd the socket + * @param buffer string to append data to + * @param count max amount of data to read + * @returns number of bytes appended to the string + */ int _dbus_read_socket (int fd, DBusString *buffer, @@ -129,6 +153,16 @@ _dbus_read_socket (int fd, return _dbus_read (fd, buffer, count); } +/** + * Like _dbus_write(), but only supports sockets + * and is thus available on Windows. + * + * @param fd the file descriptor to write + * @param buffer the buffer to write data from + * @param start the first byte in the buffer to write + * @param len the number of bytes to try to write + * @returns the number of bytes written or -1 on error + */ int _dbus_write_socket (int fd, const DBusString *buffer, @@ -138,6 +172,19 @@ _dbus_write_socket (int fd, return _dbus_write (fd, buffer, start, len); } +/** + * Like _dbus_write_two() but only works on sockets and is thus + * available on Windows. + * + * @param fd the file descriptor + * @param buffer1 first buffer + * @param start1 first byte to write in first buffer + * @param len1 number of bytes to write from first buffer + * @param buffer2 second buffer, or #NULL + * @param start2 first byte to write in second buffer + * @param len2 number of bytes to write in second buffer + * @returns total bytes written from both buffers, or -1 on error + */ int _dbus_write_socket_two (int fd, const DBusString *buffer1, @@ -157,9 +204,12 @@ _dbus_write_socket_two (int fd, * the data it reads to the DBusString buffer. It appends * up to the given count, and returns the same value * and same errno as read(). The only exception is that - * _dbus_read() handles EINTR for you. _dbus_read() can + * _dbus_read() handles EINTR for you. Also, _dbus_read() can * return ENOMEM, even though regular UNIX read doesn't. * + * Unlike _dbus_read_socket(), _dbus_read() is not available + * on Windows. + * * @param fd the file descriptor to read from * @param buffer the buffer to append data to * @param count the amount of data to read @@ -2441,7 +2491,7 @@ _dbus_get_autolaunch_address (DBusString *address, * we might want to use the registry instead of a file for * this, and I'm not sure how we'd ensure the uuid gets created. * - * @param guid to init with the machine's uuid + * @param machine_id guid to init with the machine's uuid * @param create_if_not_found try to create the uuid if it doesn't exist * @param error the error return * @returns #FALSE if the error is set diff --git a/dbus/dbus-transport-socket.c b/dbus/dbus-transport-socket.c index 183604b7..76a6fcfb 100644 --- a/dbus/dbus-transport-socket.c +++ b/dbus/dbus-transport-socket.c @@ -1258,6 +1258,14 @@ error: return NULL; } +/** + * Opens a TCP socket transport. + * + * @param entry the address entry to try opening as a tcp transport. + * @param transport_p return location for the opened transport + * @param error error to be set + * @returns result of the attempt + */ DBusTransportOpenResult _dbus_transport_open_socket(DBusAddressEntry *entry, DBusTransport **transport_p, diff --git a/dbus/dbus-transport-unix.c b/dbus/dbus-transport-unix.c index 40b27eae..16239e61 100644 --- a/dbus/dbus-transport-unix.c +++ b/dbus/dbus-transport-unix.c @@ -108,6 +108,14 @@ _dbus_transport_new_for_domain_socket (const char *path, return NULL; } +/** + * Opens platform specific transport types. + * + * @param entry the address entry to try opening + * @param transport_p return location for the opened transport + * @param error error to be set + * @returns result of the attempt + */ DBusTransportOpenResult _dbus_transport_open_platform_specific (DBusAddressEntry *entry, DBusTransport **transport_p, diff --git a/dbus/dbus-types.h b/dbus/dbus-types.h index d45c2516..81943dfd 100644 --- a/dbus/dbus-types.h +++ b/dbus/dbus-types.h @@ -85,6 +85,8 @@ typedef dbus_uint32_t dbus_bool_t; * C99 requires a 64-bit type and most likely all interesting * compilers support one. GLib for example flat-out requires * a 64-bit type. + * + * You probably want to just assume #DBUS_HAVE_INT64 is always defined. */ /** @@ -96,6 +98,8 @@ typedef dbus_uint32_t dbus_bool_t; * C99 requires a 64-bit type and most likely all interesting * compilers support one. GLib for example flat-out requires * a 64-bit type. + * + * You probably want to just assume #DBUS_HAVE_INT64 is always defined. */ /** diff --git a/dbus/dbus-uuidgen.c b/dbus/dbus-uuidgen.c index 8da83960..0d1f28c0 100644 --- a/dbus/dbus-uuidgen.c +++ b/dbus/dbus-uuidgen.c @@ -70,7 +70,7 @@ return_uuid (DBusGUID *uuid, * @param uuid_p out param to return the uuid * @param create_if_not_found whether to create it if not already there * @param error error return - * @param returns #FALSE if error is set + * @returns #FALSE if error is set */ dbus_bool_t dbus_internal_do_not_use_get_uuid (const char *filename, @@ -109,7 +109,7 @@ dbus_internal_do_not_use_get_uuid (const char *filename, * the libdbus soname. * * @param uuid_p out param to return the uuid - * @param returns #FALSE if no memory + * @returns #FALSE if no memory */ dbus_bool_t dbus_internal_do_not_use_create_uuid (char **uuid_p) |