doc/Reference.md in ruby-dbus-0.11.2 vs doc/Reference.md in ruby-dbus-0.12.0

@@ -22,43 +22,71 @@
 
 #### Calling Methods
 
 1. {DBus.session_bus Connect to the session bus};
    {DBus::Connection#[] get the screensaver service}
-   {DBus::Service#object and its screensaver object}.
+   {DBus::Service#[] and its screensaver object}.
 2. Perform {DBus::ProxyObject#introspect explicit introspection}
    to define the interfaces and methods
    on the {DBus::ProxyObject object proxy}
 ([I#28](https://github.com/mvidner/ruby-dbus/issues/28)).
 3. Call one of its methods in a loop, solving [xkcd#196](http://xkcd.com/196).
 
  
+
     mybus = DBus.session_bus
     service = mybus['org.freedesktop.ScreenSaver']
-    object = service.object '/ScreenSaver'
+    object = service['/ScreenSaver']
     object.introspect
     loop do
         object.SimulateUserActivity
         sleep 5 * 60
     end
 
 ##### Retrieving Return Values
 
-A method proxy always returns an array of values. This is to
+A method proxy simply returns a value.
+In this example SuspendAllowed returns a boolean:
+
+    mybus = DBus.session_bus
+    pm_s = mybus['org.freedesktop.PowerManagement']
+    pm_o = pm_s['/org/freedesktop/PowerManagement']
+    pm_o.introspect
+    pm_i = pm_o['org.freedesktop.PowerManagement']
+
+    if pm_i.CanSuspend
+      pm_i.Suspend
+    end
+
+###### Multiple Return Values
+
+In former versions of this library,
+a method proxy always returned an array of values. This was to
 accomodate the rare cases of a DBus method specifying more than one
-*out* parameter. For nearly all methods you should use `Method[0]` or
+*out* parameter. For compatibility, the behavior is preserved if you
+construct a {DBus::ProxyObject} with {DBus::ApiOptions::A0},
+which is what {DBus::Service#object} does.
+
+For nearly all methods you used `Method[0]` or
 `Method.first`
 ([I#30](https://github.com/mvidner/ruby-dbus/issues/30)).
     
+    mybus = DBus.session_bus
+    pm_s = mybus['org.freedesktop.PowerManagement']
+    # use legacy compatibility API
+    pm_o = pm_s.object['/org/freedesktop/PowerManagement']
+    pm_o.introspect
+    pm_i = pm_o['org.freedesktop.PowerManagement']
+
     # wrong
-    if upower_i.SuspendAllowed    # [false] is true!
-      upower_i.Suspend
-    end
+    # if pm_i.CanSuspend
+    #   pm_i.Suspend                # [false] is true!
+    # end
 
     # right
-    if upower_i.SuspendAllowed[0]
-      upower_i.Suspend
+    if pm_i.CanSuspend[0]
+      pm_i.Suspend
     end
 
 #### Accessing Properties
 
 To access properties, think of the {DBus::ProxyObjectInterface interface} as a
@@ -66,11 +94,11 @@
 or use {DBus::ProxyObjectInterface#all_properties} to get
 an actual Hash of them.
 
     sysbus = DBus.system_bus
     upower_s = sysbus['org.freedesktop.UPower']
-    upower_o = upower_s.object '/org/freedesktop/UPower'
+    upower_o = upower_s['/org/freedesktop/UPower']
     upower_o.introspect
     upower_i = upower_o['org.freedesktop.UPower']
 
     on_battery = upower_i['OnBattery']
 
@@ -110,23 +138,25 @@
     login_s = sysbus['org.freedesktop.login1'] # part of systemd
     login_o = login_s.object '/org/freedesktop/login1'
     login_o.introspect
     login_o.default_iface = 'org.freedesktop.login1.Manager'
 
+    main = DBus::Main.new
+    main << sysbus
+
     # to trigger this signal, login on the Linux console
     login_o.on_signal("SessionNew") do |name, opath|
       puts "New session: #{name}"
 
       session_o = login_s.object(opath)
       session_o.introspect
       session_i = session_o['org.freedesktop.login1.Session']
       uid, user_opath = session_i['User']
       puts "Its UID: #{uid}"
+      main.quit
     end
 
-    main = DBus::Main.new
-    main << sysbus
     main.run
 
 ### Intermediate Concepts
 #### Names
 #### Types and Values, D-Bus -> Ruby
@@ -172,11 +202,11 @@
 
 ##### Byte Arrays
 
 If a byte array (`ay`) is expected you can pass a String too.
 The bytes sent are according to the string's
-[encoding](http://ruby-doc.org/core-1.9.3/Encoding.html).
+[encoding](http://ruby-doc.org/core-2.0.0/Encoding.html).
 
 ##### nil
 
 `nil` is not allowed by D-Bus and attempting to send it raises an exception
 (but see [I#16](https://github.com/mvidner/ruby-dbus/issues/16)).
@@ -185,11 +215,14 @@
 #### Errors
 
 D-Bus calls can reply with an error instead of a return value. An error is
 translated to a Ruby exception, an instance of {DBus::Error}.
 
+    nm_o = DBus.system_bus["org.freedesktop.NetworkManager"]["/org/freedesktop/NetworkManager"]
+    nm_o.introspect
+    nm = nm_o["org.freedesktop.NetworkManager"]
     begin
-        network_manager.sleep
+        nm.Sleep(false)
     rescue DBus::Error => e
         puts e unless e.name == "org.freedesktop.NetworkManager.AlreadyAsleepOrAwake"
     end
 
 #### Interfaces