More documentation.

diff --git a/lsp-dbus.a.8.adoc b/lsp-dbus.a.8.adoc
index 92ce4a98fdedaa02f7f0c5bb2d7390499929aeb2..a5cc14ffb5794ad54ac57947ab99ddf4bcc9548e 100644 (file)
--- a/lsp-dbus.a.8.adoc
+++ b/lsp-dbus.a.8.adoc
@@ -35,9 +35,10 @@ Note that *lsp-dbus.a* depends on _FOOP_ and _prog1_ from *lsp-misc.a*.
 
 (*load "lsp-dbus.lsp")::
 
-The main file, *lsp-dbus.lsp*, includes connection setup and client
-registration as part of its loading. Currently it connects on the
-system bus (only). It also installs the funcion _main-loop_ as
+The main file, *lsp-dbus.lsp*, includes connection setup (see
+*:initialize* below) and client registration (i.e. issuing the dbus
+"Hello():s" message as part of its loading. Currently it connects on
+the system bus (only). It also installs the funcion _main-loop_ as
 _prompt-event_ function for processing any unsolicited messages from
 dbus (so called "signals").
 
@@ -120,12 +121,20 @@ function, either via an explicit call following the handshake or
 "automagically" as part of the _main-loop_ function that gets
 installed as as _prompt-event_ function.
 +
-==== Return value:
-+
+.Return value:
+[caption=""]
+====
 The return value of *:invoke* is the METHOD_REPLY message reduced into
-an association list of the headers extended with the reoly value
-wrapped into an association keyed by the empty string. The actual
-return value is thus selected with _(-1 -1 -1)_
+an association list of the headers (with the _Dbus_ header symbols as
+keys) extended with the method return value as a list wrapped into a
+final association that is keyed by the empty string.
+
+In other words, the template for using *:invoke* may look like the
+following:
+----
+(if (:invoke ...) ($it -1 -1 -1))
+----
+====
 
 (*Dbus:process-all-pending*)::
 
@@ -135,10 +144,10 @@ messages by invoking their associated handler functions.
 (*prompt-event Dbus:main-loop*)::
 
 The _main-loop_ function is set up as _prompt-event_ function for a
-_net-select_ on both stdin and the dbus socket as well as to process
-all pending signal messages. Any input from dbus, which are signal
-messages, are added to the pending list, which also is processed one
-message at a time until empty.
+combined _net-select_ on both stdin and the dbus socket as well as to
+process all pending signal messages. Any input from dbus, which are
+signal messages, are added to the pending list, which also is
+processed one message at a time until empty.
 +
 Note that newlisp uses readline for input but that this is not
 activated in _main-loop_. Therefore line editing is not available
@@ -147,12 +156,53 @@ and enter the "normal" command line input state for a single line
 input (with line editing), or an initial newline for multi-line input
 that is "submitted" by means of two newlines.
 
-(*:handler* _OBJ_ _KEY_ _HANDLER_):: This function registers a handler
-callback for a key that is a string composed as
-"path:interface.member(signature)". The handler function takes a
-single argument, which is the list of unmarshalled actual call
+(*:handler* _OBJ_ _KEY_ _HANDLER_)::
+
+This function registers a handler callback for a key that is a string
+composed as "path:interface.member(signature)". The handler function
+takes a single argument, which is the list of unmarshalled actual call
 arguments.
 
+(*DbusConnection* _PATH)::
+
+The _DbusConnection_ context is a FOOP implementation intended for the
+dbus socket connection. Each _(DbusConnection PATH)_ is intended to be
+like a real object that contains state, namely the opened socket file
+descriptor, the connection name given to it by DBus on connection and
+and the messaging serial.
+
+(*:serial++* _OBJECT_)::
+
+This method increments the serial of the given object.
+
+(*:open-socket* _OBJECT_)::
+
+This method opens the path and assignes the socket file descriptor of
+the given object. Before that though, if the socket file descriptor is
+non-negative then that file descriptor is closed before opening the
+object's path.
+
+(*:read-message* _OBJECT_)
+
+This method reads the next message by reading data from the socket
+successively while there's something to read within a millisecond.
+
+(*:handshake* _OBJECT_ _MESSAGE_ [_PATTERN_])
+
+This method performs a "raw" text-based handshake on the connection,
+which means to send the given message and then read and return the
+response message. If a _PATTERN_ is given, then the response must
+match the pattern (assigning the automatic variables $1 etc according
+to the pattern). The method returns nil if the given pattern is not
+matched. Note that this method is used only during connection setup
+and dbus communication uses its own marshalling subsequently.
+
+(*:initialize* _OBJECT_  [_USER_])
+
+This method performs the connection set up including the very first
+newline and the subsequent AUTH handshake. It ends with the connection
+in "BEGIN" mode and returns the received connection name.
+
 === MARSHALLING
 
 dbus documentation uses the terms "marshalling" and "unmarshalling"