fix up harsh language in comment

Sorry about this Havoc.

1 files changed, 22 insertions, 18 deletions

diff --git a/src/eggdbus/eggdbusconnection.c b/src/eggdbus/eggdbusconnection.c
index 5477712..e36dc2c 100644
--- a/src/eggdbus/eggdbusconnection.c
+++ b/src/eggdbus/eggdbusconnection.c
@@ -361,14 +361,13 @@ filter_function_handle_signal (DBusConnection *dconnection,
    *   this field so it is reliable; the field is only meaningful in
    *   combination with the message bus."
    *
-   * So, yeah. Fucking great. So we need to maintain a mapping from
-   * unique names into well-known names to determine if we should send
-   * the signal on to the proxy. Thanks D-Bus spec authors.
+   * Since our proxies can contain well-known names, we need to
+   * maintain a mapping from unique names into well-known names to
+   * determine what proxies to emit the signal on. This is what the
+   * EggDBusBusNameTracker class does.
    *
-   * Actually, besides tracking all this crap (which is difficult code
-   * if you want to do it Async) [1], suppose for a while that the
-   * unique name :1.42 owns both of the well-known names
-   * com.example.Foo and com.example.Bar.
+   * However, suppose for a while that the unique name :1.42 owns both
+   * of the well-known names com.example.Foo and com.example.Bar.
    *
    * Now, also assume that the name owner emits a signal on the object
    * '/' on the service com.example.Bar. But the message bus rewrites
@@ -376,18 +375,20 @@ filter_function_handle_signal (DBusConnection *dconnection,
    * :1.42. So on the client side we don't really know whether this
    * signal is for com.example.Foo or for com.example.Bar.
    *
-   * Heck, suppose both services implements a generic interface,
-   * say, org.freedesktop.Service (a hypothetical interface that
-   * all services could implement) with a signal Changed(). Now,
-   * is the Changed() signal we receive from :1.42 supposed to
-   * come from Foo or from Bar? FAIL.
+   * Now suppose both services implements a generic interface, say,
+   * org.freedesktop.Service (a hypothetical interface that all
+   * services could implement) with a signal Changed(). Now, is the
+   * Changed() signal we receive from :1.42 supposed to come from Foo
+   * or from Bar? We don't know.
    *
-   * So the D-Bus spec is slightly broken in this regard. The only
-   * possible remediation is to make services use a private tree for
-   * their objects (e.g. the name com.example.Foo uses objects in the
-   * /com/example/Foo subtree, ditto for com.example.Bar). Which, as a
-   * matter of fact, is what is recommended.  Still, there's a couple
-   * of services in the wild for which this is not true.
+   * So the D-Bus spec is slightly broken in this regard insofar that
+   * _broken_ programs like the above can trigger situations like
+   * these. The only possible remediation is to make services use a
+   * private namespace for their objects (e.g. the name
+   * com.example.Foo uses objects in the /com/example/Foo namsspace,
+   * ditto for com.example.Bar). Which, as a matter of fact, is what
+   * is recommended.  Still, there's a couple of services in the wild
+   * for which this is not true.
    *
    * So, back to reality. How do we know which proxy to route it to?
    *
@@ -396,6 +397,9 @@ filter_function_handle_signal (DBusConnection *dconnection,
    * [1] : on the upside, tracking all this stuff is immensely useful;
    * it means we can easily provide a meaningful :owner property on
    * EggDBusObjectProxy.
+   *
+   * See also http://0pointer.de/blog/projects/versioning-dbus.html
+   * for details
    */
 
   well_known_names = egg_dbus_bus_name_tracker_get_known_well_known_bus_names_for_unique_bus_name (priv->bus_name_tracker,