2006-10-27 Havoc Pennington <hp@redhat.com>

	* dbus/dbus-connection.c (dbus_connection_open_private): document
	how to choose shared vs. private connections

diff --git a/ChangeLog b/ChangeLog
index f0d4d89f045c47f800147dc0f25c2f6dbd84a5b4..7e5458b1ef6227b52ae336be6df15b9d60da41c3 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2006-10-27  Havoc Pennington  <hp@redhat.com>
+       
+       * dbus/dbus-connection.c (dbus_connection_open_private): document
+       how to choose shared vs. private connections
+
 2006-10-27  Havoc Pennington  <hp@redhat.com>
 
        * dbus/dbus-test.c: enclose more of the file in the

diff --git a/dbus/dbus-connection.c b/dbus/dbus-connection.c
index db6255884722f27f04d8a16539001d7ebe937af6..552ecfd8dea351e405a710ba287a290842a49cfb 100644 (file)
--- a/dbus/dbus-connection.c
+++ b/dbus/dbus-connection.c
@@ -2381,6 +2381,11 @@ _dbus_connection_block_pending_call (DBusPendingCall *pending)
  * Because this connection is shared, no user of the connection
  * may call dbus_connection_close(). However, when you are done with the
  * connection you should call dbus_connection_unref().
+ *
+ * @note Prefer dbus_connection_open() to dbus_connection_open_private()
+ * unless you have good reason; connections are expensive enough
+ * that it's wasteful to create lots of connections to the same
+ * server.
  * 
  * @param address the address.
  * @param error address where an error can be returned.
@@ -2419,7 +2424,12 @@ dbus_connection_open (const char     *address,
  * (The dbus_connection_close() can be skipped if the
  * connection is already known to be disconnected, for example
  * if you are inside a handler for the Disconnected signal.)
- * 
+ *
+ * @note Prefer dbus_connection_open() to dbus_connection_open_private()
+ * unless you have good reason; connections are expensive enough
+ * that it's wasteful to create lots of connections to the same
+ * server.
+ *
  * @param address the address.
  * @param error address where an error can be returned.
  * @returns new connection, or #NULL on failure.