2003-04-29 Havoc Pennington <hp@redhat.com>

	* glib/dbus-gmain.c: docs cleanups

	* dbus/dbus-types.h: add docs on int64 types

	* dbus/dbus-memory.c: fix docs to avoid putting private API in
	public API docs section

6 files changed, 134 insertions, 36 deletions

diff --git a/ChangeLog b/ChangeLog
index d9477709..09c9e371 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,14 @@
 2003-04-29  Havoc Pennington  <hp@redhat.com>
 
+	* glib/dbus-gmain.c: docs cleanups
+
+	* dbus/dbus-types.h: add docs on int64 types
+
+	* dbus/dbus-memory.c: fix docs to avoid putting private API in
+	public API docs section
+
+2003-04-29  Havoc Pennington  <hp@redhat.com>
+
 	* dbus-1.pc.in, dbus-glib-1.pc.in: rename these from
 	dbus-1.0.pc.in, dbus-glib-1.0.pc.in. As these change with the
 	parallel install API version, not with the D-BUS package version.
diff --git a/dbus/dbus-errors.c b/dbus/dbus-errors.c
index f7636287..3cf52363 100644
--- a/dbus/dbus-errors.c
+++ b/dbus/dbus-errors.c
@@ -39,7 +39,7 @@
  *
  * @code
  * DBusError error;
- * _dbus_error_init (&error);
+ * dbus_error_init (&error);
  * dbus_some_function (arg1, arg2, &error);
  * if (dbus_error_is_set (&error))
  *   {
@@ -178,6 +178,8 @@ dbus_error_free (DBusError *error)
  * message will be deduced from the name. If the error name is unknown
  * to D-BUS the default message will be totally useless, though.
  *
+ * @todo should be called dbus_error_set_const() 
+ * 
  * @param error the error.
  * @param name the error name (not copied!!!)
  * @param message the error message (not copied!!!)
@@ -214,7 +216,7 @@ dbus_set_error_const (DBusError  *error,
  * src is reinitialized to an empty error. dest may not
  * contain an existing error. If the destination is
  * #NULL, just frees and reinits the source error.
- *
+ * 
  * @param src the source error
  * @param dest the destination error or #NULL
  */
@@ -288,6 +290,8 @@ dbus_error_is_set (const DBusError *error)
  * If no memory can be allocated for the error message, 
  * an out-of-memory error message will be set instead.
  *
+ * @todo should be called dbus_error_set()
+ *
  * @todo stdio.h shouldn't be included in this file,
  * should write _dbus_string_append_printf instead
  * 
diff --git a/dbus/dbus-memory.c b/dbus/dbus-memory.c
index c42ef466..dce1dded 100644
--- a/dbus/dbus-memory.c
+++ b/dbus/dbus-memory.c
@@ -27,7 +27,6 @@
 #include "dbus-list.h"
 #include <stdlib.h>
 
-
 /**
  * @defgroup DBusMemory Memory Allocation
  * @ingroup  DBus
@@ -36,6 +35,20 @@
  * Functions and macros related to allocating and releasing
  * blocks of memory.
  *
+ */
+
+/**
+ * @defgroup DBusMemoryInternals Memory allocation implementation details
+ * @ingroup  DBusInternals
+ * @brief internals of dbus_malloc() etc.
+ *
+ * Implementation details related to allocating and releasing blocks
+ * of memory.
+ */
+
+/**
+ * @addtogroup DBusMemory
+ *
  * @{
  */
 
@@ -74,6 +87,14 @@
  * @param memory the memory to free
  */
 
+/** @} */ /* end of public API docs */
+
+/**
+ * @addtogroup DBusMemoryInternals
+ *
+ * @{
+ */
+
 #ifdef DBUS_BUILD_TESTS
 static dbus_bool_t debug_initialized = FALSE;
 static int fail_nth = -1;
@@ -387,6 +408,15 @@ set_guards (void       *real_block,
 
 #endif
 
+/** @} */ /* End of internals docs */
+
+
+/**
+ * @addtogroup DBusMemory
+ *
+ * @{
+ */
+
 /**
  * Allocates the given number of bytes, as with standard
  * malloc(). Guaranteed to return #NULL if bytes is zero
@@ -625,6 +655,15 @@ dbus_free_string_array (char **str_array)
     }
 }
 
+/** @} */ /* End of public API docs block */
+
+
+/**
+ * @addtogroup DBusMemoryInternals
+ *
+ * @{
+ */
+
 /**
  * _dbus_current_generation is used to track each
  * time that dbus_shutdown() is called, so we can
@@ -652,36 +691,6 @@ _DBUS_DEFINE_GLOBAL_LOCK (shutdown_funcs);
 static ShutdownClosure *registered_globals = NULL;
 
 /**
- * The D-BUS library keeps some internal global variables, for example
- * to cache the username of the current process.  This function is
- * used to free these global variables.  It is really useful only for
- * leak-checking cleanliness and the like. WARNING: this function is
- * NOT thread safe, it must be called while NO other threads are using
- * D-BUS. You cannot continue using D-BUS after calling this function,
- * as it does things like free global mutexes created by
- * dbus_threads_init(). To use a D-BUS function after calling
- * dbus_shutdown(), you have to start over from scratch, e.g. calling
- * dbus_threads_init() again.
- */
-void
-dbus_shutdown (void)
-{
-  while (registered_globals != NULL)
-    {
-      ShutdownClosure *c;
-
-      c = registered_globals;
-      registered_globals = c->next;
-      
-      (* c->func) (c->data);
-      
-      dbus_free (c);
-    }
-
-  _dbus_current_generation += 1;
-}
-
-/**
  * Register a cleanup function to be called exactly once
  * the next time dbus_shutdown() is called.
  *
@@ -713,4 +722,43 @@ _dbus_register_shutdown_func (DBusShutdownFunction  func,
   return TRUE;
 }
 
-/** @} */
+/** @} */ /* End of private API docs block */
+
+
+/**
+ * @addtogroup DBusMemory
+ *
+ * @{
+ */
+
+/**
+ * The D-BUS library keeps some internal global variables, for example
+ * to cache the username of the current process.  This function is
+ * used to free these global variables.  It is really useful only for
+ * leak-checking cleanliness and the like. WARNING: this function is
+ * NOT thread safe, it must be called while NO other threads are using
+ * D-BUS. You cannot continue using D-BUS after calling this function,
+ * as it does things like free global mutexes created by
+ * dbus_threads_init(). To use a D-BUS function after calling
+ * dbus_shutdown(), you have to start over from scratch, e.g. calling
+ * dbus_threads_init() again.
+ */
+void
+dbus_shutdown (void)
+{
+  while (registered_globals != NULL)
+    {
+      ShutdownClosure *c;
+
+      c = registered_globals;
+      registered_globals = c->next;
+      
+      (* c->func) (c->data);
+      
+      dbus_free (c);
+    }
+
+  _dbus_current_generation += 1;
+}
+
+/** @} */ /** End of public API docs block */
diff --git a/dbus/dbus-timeout.c b/dbus/dbus-timeout.c
index 1a2d2965..625fbb74 100644
--- a/dbus/dbus-timeout.c
+++ b/dbus/dbus-timeout.c
@@ -137,7 +137,7 @@ _dbus_timeout_set_interval (DBusTimeout *timeout,
  * only used in the message bus daemon implementation.
  *
  * @param timeout the timeout
- * @param interval the new interval
+ * @param enabled #TRUE if timeout should be enabled.
  */
 void
 _dbus_timeout_set_enabled (DBusTimeout  *timeout,
diff --git a/dbus/dbus-types.h b/dbus/dbus-types.h
index e9bfca84..854b6526 100644
--- a/dbus/dbus-types.h
+++ b/dbus/dbus-types.h
@@ -77,6 +77,37 @@ typedef dbus_uint32_t  dbus_unichar_t;
  * A 16-bit signed integer on all platforms.
  */
 
+
+/**
+ * @typedef dbus_uint64_t
+ *
+ * A 64-bit unsigned integer on all platforms that support it.
+ * If supported, #DBUS_HAVE_INT64 will be defined.
+ */
+
+/**
+ * @typedef dbus_int64_t
+ *
+ * A 64-bit signed integer on all platforms that support it.
+ * If supported, #DBUS_HAVE_INT64 will be defined.
+ */
+
+/**
+ * @def DBUS_INT64_CONSTANT
+ *
+ * Declare a 64-bit signed integer constant. The macro
+ * adds the necessary "LL" or whatever after the integer,
+ * giving a literal such as "325145246765LL"
+ */
+
+/**
+ * @def DBUS_UINT64_CONSTANT
+ *
+ * Declare a 64-bit unsigned integer constant. The macro
+ * adds the necessary "ULL" or whatever after the integer,
+ * giving a literal such as "325145246765ULL"
+ */
+
 /** @} */
 
 #endif /* DBUS_TYPES_H */
diff --git a/glib/dbus-gmain.c b/glib/dbus-gmain.c
index dd9ea375..c120a6c1 100644
--- a/glib/dbus-gmain.c
+++ b/glib/dbus-gmain.c
@@ -394,8 +394,11 @@ create_source (void         *connection_or_server,
 /**
  * Sets the watch and timeout functions of a #DBusConnection
  * to integrate the connection with the GLib main loop.
+ * Pass in #NULL for the #GMainContext unless you're
+ * doing something specialized.
  *
  * @param connection the connection
+ * @param context the #GMainContext or #NULL for default context
  */
 void
 dbus_connection_setup_with_g_main (DBusConnection *connection,
@@ -446,11 +449,14 @@ dbus_connection_setup_with_g_main (DBusConnection *connection,
 /**
  * Sets the watch and timeout functions of a #DBusServer
  * to integrate the server with the GLib main loop.
+ * In most cases the context argument should be #NULL.
  *
  * @param server the server
+ * @param context the #GMainContext or #NULL for default
  */
 void
-dbus_server_setup_with_g_main (DBusServer *server, GMainContext *context)
+dbus_server_setup_with_g_main (DBusServer   *server,
+                               GMainContext *context)
 {
   GSource *source;