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
DBUS_BUILD_TESTS check.
* 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.
* (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.