2006-10-21 Havoc Pennington <hp@redhat.com>
+
+ * Clean up Doxygen group markers for public API so Doxygen finds
+ everything (not comprehensively fixed for private API).
+ Means all remaining Doxygen warnings are just about missing docs
+ and thus pretty simple to resolve.
+
+2006-10-21 Havoc Pennington <hp@redhat.com>
* dbus/dbus-macros.h: add DBUS_GNUC_DEPRECATED macro
#include <dbus/dbus-types.h>
#include <dbus/dbus-errors.h>
+DBUS_BEGIN_DECLS
+
+/**
+ * @addtogroup DBusAddress
+ * @{
+ */
+
typedef struct DBusAddressEntry DBusAddressEntry;
dbus_bool_t dbus_parse_address (const char *address,
char* dbus_address_unescape_value (const char *value,
DBusError *error);
+/** @} */
+
+DBUS_END_DECLS
+
#endif /* DBUS_ADDRESS_H */
DBUS_BEGIN_DECLS
+/**
+ * @addtogroup DBusBus
+ * @{
+ */
+
DBusConnection *dbus_bus_get (DBusBusType type,
DBusError *error);
DBusConnection *dbus_bus_get_private (DBusBusType type,
void _dbus_bus_notify_shared_connection_disconnected_unlocked (DBusConnection *connection);
+/** @} */
+
DBUS_END_DECLS
#endif /* DBUS_BUS_H */
DBUS_BEGIN_DECLS
+/**
+ * @addtogroup DBusConnection
+ * @{
+ */
+
typedef struct DBusWatch DBusWatch;
typedef struct DBusTimeout DBusTimeout;
typedef struct DBusPreallocatedSend DBusPreallocatedSend;
char* dbus_get_local_machine_id (void);
+/** @} */
+
DBUS_END_DECLS
#endif /* DBUS_CONNECTION_H */
DBUS_BEGIN_DECLS
+/**
+ * @addtogroup DBusErrors
+ * @{
+ */
+
typedef struct DBusError DBusError;
/**
const char *name);
dbus_bool_t dbus_error_is_set (const DBusError *error);
+/** @} */
+
DBUS_END_DECLS
#endif /* DBUS_ERROR_H */
DBUS_BEGIN_DECLS
+/**
+ * @addtogroup DBusHashTable
+ * @{
+ */
+
/** Hash iterator object. The iterator is on the stack, but its real
* fields are hidden privately.
*/
char *key,
void *value);
+/** @} */
DBUS_END_DECLS
#endif
/**
+ * @addtogroup DBusMarshal
+ *
+ * @{
+ */
+
+/**
* This is used rather than a bool for high visibility
*/
typedef enum
typedef enum
{
#define _DBUS_NEGATIVE_VALIDITY_COUNT 4
- DBUS_VALIDITY_UNKNOWN_OOM_ERROR = -4,
+ DBUS_VALIDITY_UNKNOWN_OOM_ERROR = -4, /**< can't determine validity due to OOM */
DBUS_INVALID_FOR_UNKNOWN_REASON = -3,
DBUS_VALID_BUT_INCOMPLETE = -2,
DBUS_VALIDITY_UNKNOWN = -1,
- DBUS_VALID = 0,
+ DBUS_VALID = 0, /**< the data is valid */
DBUS_INVALID_UNKNOWN_TYPECODE = 1,
DBUS_INVALID_MISSING_ARRAY_ELEMENT_TYPE = 2,
DBUS_INVALID_SIGNATURE_TOO_LONG = 3, /* this one is impossible right now since
DBUS_INVALID_ALIGNMENT_PADDING_NOT_NUL = 9,
DBUS_INVALID_BOOLEAN_NOT_ZERO_OR_ONE = 10,
DBUS_INVALID_NOT_ENOUGH_DATA = 11,
- DBUS_INVALID_TOO_MUCH_DATA = 12,
+ DBUS_INVALID_TOO_MUCH_DATA = 12, /**< trailing junk makes it invalid */
DBUS_INVALID_BAD_BYTE_ORDER = 13,
DBUS_INVALID_BAD_PROTOCOL_VERSION = 14,
DBUS_INVALID_BAD_MESSAGE_TYPE = 15,
DECLARE_DBUS_NAME_CHECK(bus_name);
DECLARE_DBUS_NAME_CHECK(signature);
+/** @} */
+
#endif /* DBUS_MARSHAL_VALIDATE_H */
DBUS_BEGIN_DECLS
+/**
+ * @addtogroup DBusMemory
+ * @{
+ */
+
void* dbus_malloc (size_t bytes);
void* dbus_malloc0 (size_t bytes);
void* dbus_realloc (void *memory,
void dbus_shutdown (void);
+/** @} */
+
DBUS_END_DECLS
#endif /* DBUS_MEMORY_H */
DBUS_BEGIN_DECLS
+/**
+ * @addtogroup DBusMessage
+ * @{
+ */
+
typedef struct DBusMessage DBusMessage;
typedef struct DBusMessageIter DBusMessageIter;
/**
- * DBusMessageIter struct; contains no public fields
+ * DBusMessageIter struct; contains no public fields.
*/
struct DBusMessageIter
{
int dbus_message_type_from_string (const char *type_str);
const char * dbus_message_type_to_string (int type);
+/** @} */
+
DBUS_END_DECLS
#endif /* DBUS_MESSAGE_H */
DBUS_BEGIN_DECLS
+/**
+ * @addtogroup DBusPendingCall
+ * @{
+ */
+
DBusPendingCall* dbus_pending_call_ref (DBusPendingCall *pending);
void dbus_pending_call_unref (DBusPendingCall *pending);
dbus_bool_t dbus_pending_call_set_notify (DBusPendingCall *pending,
DBusFreeFunction free_data_func);
void* dbus_pending_call_get_data (DBusPendingCall *pending,
dbus_int32_t slot);
+
+/** @} */
+
DBUS_END_DECLS
#endif /* DBUS_PENDING_CALL_H */
DBUS_BEGIN_DECLS
+/**
+ * @addtogroup DBusServer
+ * @{
+ */
+
typedef struct DBusServer DBusServer;
typedef void (* DBusNewConnectionFunction) (DBusServer *server,
void* dbus_server_get_data (DBusServer *server,
int slot);
+/** @} */
+
DBUS_END_DECLS
#endif /* DBUS_SERVER_H */
DBUS_BEGIN_DECLS
/**
+ * @addtogroup DBusSignature
+ * @{
+ */
+
+/**
* DBusSignatureIter struct; contains no public fields
*/
typedef struct
dbus_bool_t dbus_type_is_container (int typecode);
dbus_bool_t dbus_type_is_fixed (int typecode);
+/** @} */
+
DBUS_END_DECLS
#endif /* DBUS_SIGNATURE_H */
#include "dbus-sysdeps.h"
/**
- * @defgroup DBusString string class
+ * @defgroup DBusString DBusString class
* @ingroup DBusInternals
- * @brief DBusString data structure
+ * @brief DBusString data structure for safer string handling
*
* Types and functions related to DBusString. DBusString is intended
* to be a string class that makes it hard to mess up security issues
#define socklen_t int
#endif
-/**
- * @addtogroup DBusInternalsUtils
- * @{
- */
-
static dbus_bool_t
_dbus_open_socket (int *fd,
int domain,
return _dbus_read_uuid_file (&filename, machine_id, create_if_not_found, error);
}
-/** @} end of sysdeps */
-
/* tests in dbus-sysdeps-util.c */
DBUS_BEGIN_DECLS
+/**
+ * @defgroup DBusSysdepsUnix UNIX-specific internal API
+ * @ingroup DBusInternals
+ * @brief Internal system-dependent API available on UNIX only
+ * @{
+ */
+
dbus_bool_t
_dbus_close (int fd,
DBusError *error);
dbus_bool_t abstract,
DBusError *error);
+/** @} */
+
DBUS_END_DECLS
#endif /* DBUS_SYSDEPS_UNIX_H */
_DBUS_DEFINE_GLOBAL_LOCK (sid_atom_cache);
/**
- * @addtogroup DBusInternalsUtils
+ * @defgroup DBusSysdeps Internal system-dependent API
+ * @ingroup DBusInternals
+ * @brief Internal system-dependent API available on UNIX and Windows
+ *
+ * The system-dependent API has a dual purpose. First, it encapsulates
+ * all usage of operating system APIs for ease of auditing and to
+ * avoid cluttering the rest of the code with bizarre OS quirks and
+ * headers. Second, it abstracts different operating system APIs for
+ * portability.
+ *
* @{
*/
DBUS_BEGIN_DECLS
+/**
+ * @addtogroup DBusSysdeps
+ *
+ * @{
+ */
+
/* The idea of this file is to encapsulate everywhere that we're
* relying on external libc features, for ease of security
* auditing. The idea is from vsftpd. This also gives us a chance to
DBusError *error);
+/** @} */
+
DBUS_END_DECLS
#endif /* DBUS_SYSDEPS_H */
DBUS_BEGIN_DECLS
+/**
+ * @addtogroup DBusThreads
+ * @{
+ */
+
typedef struct DBusMutex DBusMutex;
typedef struct DBusCondVar DBusCondVar;
dbus_bool_t dbus_threads_init (const DBusThreadFunctions *functions);
dbus_bool_t dbus_threads_init_default (void);
+/** @} */
+
DBUS_END_DECLS
#endif /* DBUS_THREADS_H */
DBUS_BEGIN_DECLS
-typedef struct DBusTimeoutList DBusTimeoutList;
+/**
+ * @addtogroup DBusTimeoutInternals
+ * @{
+ */
/* Public methods on DBusTimeout are in dbus-connection.h */
+typedef struct DBusTimeoutList DBusTimeoutList;
+
typedef dbus_bool_t (* DBusTimeoutHandler) (void *data);
DBusTimeout* _dbus_timeout_new (int interval,
dbus_bool_t enabled);
+/** @} */
+
DBUS_END_DECLS
#endif /* DBUS_TIMEOUT_H */
*/
/**
+ * @def DBUS_HAVE_INT64
+ *
+ * Defined if 64-bit integers are available. Will be defined
+ * on any platform you care about, unless you care about
+ * some truly ancient UNIX, or some bizarre embedded platform.
+ *
+ * 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 should feel comfortable ignoring this macro and just using
+ * int64 unconditionally.
+ *
+ */
+
+/**
* @def DBUS_INT64_CONSTANT
*
* Declare a 64-bit signed integer constant. The macro
DBUS_BEGIN_DECLS
+/**
+ * @addtogroup DBusWatchInternals
+ * @{
+ */
+
/* Public methods on DBusWatch are in dbus-connection.h */
typedef struct DBusWatchList DBusWatchList;
DBusWatch *watch,
dbus_bool_t enabled);
+/** @} */
DBUS_END_DECLS