doc: Basic Concepts: xref'd, added signals+async.

Author: mvidner

doc/Reference.md

@@ -20,13 +20,15 @@ The following code is assumed as a prolog to all following ones
 
 #### Calling Methods
 
-1. Connect to the session bus; get the screensaver service and its
-screensaver object.
-2. Perform explicit introspection to define the interfaces and methods
-on the {DBus::ProxyObject object proxy}
-({https://github.com/mvidner/ruby-dbus/issues/28 I#28}).
-3. Get the screensaver interface
-({https://github.com/mvidner/ruby-dbus/issues/29 I#29}).
+1. {DBus.session_bus Connect to the session bus};
+   {DBus::Connection#[] get the screensaver service}
+   {DBus::Service#object 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. Get the screensaver {DBus::ProxyObject#[] interface}
+[I#29](https://github.com/mvidner/ruby-dbus/issues/29).
 4. Call one of its methods in a loop, solving [xkcd#196](http://xkcd.com/196).
 
 {include:file:doc/ex-calling-methods.body.rb}
@@ -37,7 +39,7 @@ A method proxy always returns an array of values. This is 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
 `Method.first`
-({https://github.com/mvidner/ruby-dbus/issues/30 I#30}).
+[I#30](https://github.com/mvidner/ruby-dbus/issues/30).
 
 
     # wrong
@@ -52,14 +54,41 @@ accomodate the rare cases of a DBus method specifying more than one
 
 #### Accessing Properties
 
-{include:file:doc/ex-properties.body.rb}
+To access properties, think of the {DBus::ProxyObjectInterface interface} as a
+{DBus::ProxyObjectInterface#[] hash} keyed by strings,
+or use {DBus::ProxyObjectInterface#all_properties} to get
+an actual Hash of them.
 
-#### Receiving Signals
+{include:file:doc/ex-properties.body.rb}
 
+(TODO a writable property example)
 
 #### Asynchronous Operation
+
+If a method call has a block attached, it is asynchronous and the block
+is invoked on receiving a method_return message or an error message
+
 ##### Main Loop
 
+For asynchronous operation an event loop is necessary. Use {DBus::Main}:
+
+    # [set up signal handlers...]
+    main = DBus::Main.new
+    main << mybus
+    main.run
+
+Alternately, run the GLib main loop and add your DBus connections to it via
+{DBus::Connection#glibize}.
+
+#### Receiving Signals
+
+To receive signals for a specific object and interface, use
+{DBus::ProxyObjectInterface#on\_signal}(bus, name, &block) or
+{DBus::ProxyObject#on_signal}(name, &block), for the default interface.
+[I#31](https://github.com/mvidner/ruby-dbus/issues/31)
+
+{include:file:doc/ex-signal.body.rb}
+
 ### Intermediate Concepts
 #### Names
 #### Types

doc/ex-signal.body.rb

@@ -0,0 +1,20 @@
+sysbus = DBus.system_bus
+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'
+
+# 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}"
+end
+
+main = DBus::Main.new
+main << sysbus
+main.run

doc/ex-signal.rb

@@ -0,0 +1,3 @@
+#! /usr/bin/env ruby
+require 'example-helper.rb'
+example 'ex-signal.body.rb'

lib/dbus/bus.rb

@@ -797,12 +797,14 @@ class SystemBus < ASystemBus
     include Singleton
   end
 
-  # Shortcut for the SystemBus instance
+  # Shortcut for the {SystemBus} instance
+  # @return [Connection]
   def DBus.system_bus
     SystemBus.instance
   end
 
-  # Shortcut for the SessionBus instance
+  # Shortcut for the {SessionBus} instance
+  # @return [Connection]
   def DBus.session_bus
     SessionBus.instance
   end

lib/dbus/introspect.rb

@@ -339,6 +339,7 @@ def []=(propname, value)
     end
 
     # Read all properties at once, as a hash.
+    # @return [Hash{String}]
     def all_properties
       self.object[PROPERTY_INTERFACE].GetAll(self.name)[0]
     end
@@ -377,12 +378,16 @@ def interfaces
       @interfaces.keys
     end
 
-    # Retrieves an interface of the proxy object (ProxyObjectInterface instance).
+    # Retrieves an interface of the proxy object
+    # @return [ProxyObjectInterface]
     def [](intfname)
       @interfaces[intfname]
     end
 
     # Maps the given interface name _intfname_ to the given interface _intf.
+    # @param [String] intfname
+    # @param [ProxyObjectInterface] intf
+    # @return [ProxyObjectInterface]
     def []=(intfname, intf)
       @interfaces[intfname] = intf
     end