C++ sync/async session api doc

[Alan Conway <ac...@redhat.com>]

Added some more API doc on this topic, the diff is below for rapid reading:

Index: src/qpid/client/Connection.h
===================================================================
--- src/qpid/client/Connection.h	(revision 660555)
+++ src/qpid/client/Connection.h	(working copy)
@@ -108,7 +108,39 @@
      /**
       * Create a new session on this connection.  Sessions allow
       * multiple streams of work to be multiplexed over the same
-     * connection.
+     * connection. The returned Session provides functions to send
+     * commands to the broker.
+     *
+     * Session functions are synchronous. In other words, a Session
+     * function will send a command to the broker and does not return
+     * until it receives the broker's response confirming the command
+     * was executed.
+     *
+     * AsyncSession provides asynchronous versions of the same
+     * functions.  These functions send a command to the broker but do
+     * not wait for a response.
+     *
+     * You can convert a Session s into an AsyncSession as follows:
+     * @code
+     *  #include <qpid/client/AsyncSession.h>
+     *  AsyncSession as = async(s);
+     * @endcode
+     *
+     * You can execute a single command asynchronously will a Session s
+     * like ths:
+     * @code
+     *  async(s).messageTransfer(...);
+     * @endcode
+     *
+     * Using an AsyncSession is faster for sending large numbers of
+     * commands, since each command is sent as soon as possible
+     * without waiting for the previous command to be confirmed.
+     *
+     * However with AsyncSession you cannot assume that a command has
+     * completed until you explicitly synchronize. The simplest way to
+     * do this is to call Session::sync() or AsyncSession::sync().
+     * Both of these functions wait for the broker to confirm all
+     * commands issued so far on the session.
       *
       *@param name: A name to identify the session. @see qpid::SessionId
       * If the name is empty (the default) then a unique name will be
Index: src/qpid/client/Completion.h
===================================================================
--- src/qpid/client/Completion.h	(revision 660555)
+++ src/qpid/client/Completion.h	(working copy)
@@ -29,6 +29,11 @@
  namespace qpid {
  namespace client {

+/**
+ * Returned by asynchronous commands that do not return any result.
+ * You can use this to wait for an individual command to complete.
+ * \clientapi
+ */
  class Completion
  {
  protected:
@@ -40,6 +45,7 @@

      Completion(Future f, shared_ptr<SessionImpl> s) : future(f), session(s) {}

+    /** Wait for the command to complete */
      void wait()
      {
          future.wait(*session);
Index: src/qpid/client/TypedResult.h
===================================================================
--- src/qpid/client/TypedResult.h	(revision 660555)
+++ src/qpid/client/TypedResult.h	(working copy)
@@ -27,6 +27,11 @@
  namespace qpid {
  namespace client {

+/**
+ * Returned by asynchronous commands that return a result.
+ * You can use get() to wait for completion and get the result value.
+ * \clientapi
+ */
  template <class T> class TypedResult : public Completion
  {
      T result;
@@ -35,6 +40,7 @@
  public:
      TypedResult(Future f, shared_ptr<SessionImpl> s) : Completion(f, s), 
decoded(false) {}

+    /** Wait for command to complete and return the result */
      T& get()
      {
          if (!decoded) {