Edits to doxygen comments for user documentation.

git-svn-id: https://svn.apache.org/repos/asf/incubator/qpid/trunk/qpid@651321 13f79535-47bb-0310-9956-ffa450edef68

24 files changed, 137 insertions, 137 deletions

diff --git a/cpp/src/qpid/client/AckMode.h b/cpp/src/qpid/client/AckMode.h
index 944fba655d..b411c322d8 100644
--- a/cpp/src/qpid/client/AckMode.h
+++ b/cpp/src/qpid/client/AckMode.h
@@ -29,7 +29,7 @@ namespace client {
 /**
  * DEPRECATED
  * 
- * The available acknowledgements modes for Channel (now also deprecated).
+ * The available acknowledgement modes for Channel (now also deprecated).
  */
 enum AckMode {
     /** No acknowledgement will be sent, broker can
@@ -38,7 +38,7 @@ enum AckMode {
     NO_ACK     = 0,  
     /** Each message will be automatically
         acknowledged as soon as it is delivered to the
-        application **/  
+        application. **/  
     AUTO_ACK   = 1,  
     /** Acknowledgements will be sent automatically,
         but not for each message. **/
diff --git a/cpp/src/qpid/client/Channel.h b/cpp/src/qpid/client/Channel.h
index 1c3c2c9ae8..9a22c455c4 100644
--- a/cpp/src/qpid/client/Channel.h
+++ b/cpp/src/qpid/client/Channel.h
@@ -102,11 +102,11 @@ class Channel : private sys::Runnable
      * 
      * @param transactional if true, the publishing and acknowledgement
      * of messages will be transactional and can be committed or
-     * aborted in atomic units (@see commit(), @see rollback())
+     * aborted in atomic units (@see commit(), @see rollback()).
      * 
      * @param prefetch specifies the number of unacknowledged
      * messages the channel is willing to have sent to it
-     * asynchronously
+     * asynchronously.
      */
     Channel(bool transactional = false, u_int16_t prefetch = 0);
      
@@ -115,43 +115,43 @@ class Channel : private sys::Runnable
     /**
      * Declares an exchange.
      * 
-     * In AMQP Exchanges are the destinations to which messages
+     * In AMQP, Exchanges are the destinations to which messages
      * are published. They have Queues bound to them and route
      * messages they receive to those queues. The routing rules
      * depend on the type of the exchange.
      * 
      * @param exchange an Exchange object representing the
-     * exchange to declare
+     * exchange to declare.
      * 
      * @param synch if true this call will block until a response
-     * is received from the broker
+     * is received from the broker.
      */
     void declareExchange(Exchange& exchange, bool synch = true);
     /**
-     * Deletes an exchange
+     * Deletes an exchange.
      * 
-     * @param exchange an Exchange object representing the exchange to delete
+     * @param exchange an Exchange object representing the exchange to delete.
      * 
      * @param synch if true this call will block until a response
-     * is received from the broker
+     * is received from the broker.
      */
     void deleteExchange(Exchange& exchange, bool synch = true);
     /**
-     * Declares a Queue
+     * Declares a Queue.
      * 
-     * @param queue a Queue object representing the queue to declare
+     * @param queue a Queue object representing the queue to declare.
      * 
      * @param synch if true this call will block until a response
-     * is received from the broker
+     * is received from the broker.
      */
     void declareQueue(Queue& queue, bool synch = true);
     /**
-     * Deletes a Queue
+     * Deletes a Queue.
      * 
-     * @param queue a Queue object representing the queue to delete
+     * @param queue a Queue object representing the queue to delete.
      * 
      * @param synch if true this call will block until a response
-     * is received from the broker
+     * is received from the broker.
      */
     void deleteQueue(Queue& queue, bool ifunused = false, bool ifempty = false, bool synch = true);
     /**
@@ -160,17 +160,17 @@ class Channel : private sys::Runnable
      * are used) depends on the type of the exchange.
      * 
      * @param exchange an Exchange object representing the
-     * exchange to bind to
+     * exchange to bind to.
      * 
      * @param queue a Queue object representing the queue to be
-     * bound
+     * bound.
      * 
-     * @param key the 'routing key' for the binding
+     * @param key the 'routing key' for the binding.
      * 
-     * @param args the 'binding arguments' for the binding
+     * @param args the 'binding arguments' for the binding.
      * 
      * @param synch if true this call will block until a response
-     * is received from the broker
+     * is received from the broker.
      */
     void bind(const Exchange& exchange, const Queue& queue,
               const std::string& key,
@@ -180,13 +180,13 @@ class Channel : private sys::Runnable
     /**
      * For a transactional channel this will commit all
      * publications and acknowledgements since the last commit (or
-     * the channel was opened if there has been no previous
+     * the channel that was opened if there has been no previous
      * commit). This will cause published messages to become
      * available to consumers and acknowledged messages to be
      * consumed and removed from the queues they were dispatched
      * from.
      * 
-     * Transactionailty of a channel is specified when the channel
+     * A channel is specified as transactional or not when the channel
      * object is created (@see Channel()).
      */
     void commit();
@@ -194,7 +194,7 @@ class Channel : private sys::Runnable
     /**
      * For a transactional channel, this will rollback any
      * publications or acknowledgements. It will be as if the
-     * ppblished messages were never sent and the acknowledged
+     * published messages were never sent and the acknowledged
      * messages were never consumed.
      */
     void rollback();
@@ -207,7 +207,7 @@ class Channel : private sys::Runnable
     uint32_t getPrefetch() { return prefetch; }
 
     /**
-     * Start message dispatching on a new thread
+     * Start message dispatching on a new thread.
      */
     void start();
 
@@ -217,13 +217,13 @@ class Channel : private sys::Runnable
      */
     void close();
 
-    /** True if the channel is transactional */
+    /** True if the channel is transactional. */
     bool isTransactional() { return transactional; }
     
-    /** True if the channel is open */
+    /** True if the channel is open. */
     bool isOpen() const;
 
-    /** Return the protocol version */
+    /** Return the protocol version. */
     framing::ProtocolVersion getVersion() const { return version ; }
     
     /**
@@ -232,11 +232,11 @@ class Channel : private sys::Runnable
      * asynchronously.
      * 
      * @param queue a Queue instance representing the queue to
-     * consume from
+     * consume from.
      * 
      * @param tag an identifier to associate with the consumer
      * that can be used to cancel its subscription (if empty, this
-     * will be assigned by the broker)
+     * will be assigned by the broker).
      * 
      * @param listener a pointer to an instance of an
      * implementation of the MessageListener interface. Messages
@@ -248,10 +248,10 @@ class Channel : private sys::Runnable
      * should assume for this consumer. @see AckMode
      * 
      * @param noLocal if true, this consumer will not be sent any
-     * message published by this connection
+     * message published by this connection.
      * 
      * @param synch if true this call will block until a response
-     * is received from the broker
+     * is received from the broker.
      */
     void consume(
         Queue& queue, const std::string& tag, MessageListener* listener, 
@@ -265,7 +265,7 @@ class Channel : private sys::Runnable
      * request that set up the subscription to be cancelled.
      * 
      * @param synch if true this call will block until a response
-     * is received from the broker
+     * is received from the broker.
      */
     void cancel(const std::string& tag, bool synch = true);
     /**
@@ -274,7 +274,7 @@ class Channel : private sys::Runnable
      * @param msg a message object that will contain the message
      * headers and content if the call completes.
      * 
-     * @param queue the queue to consume from
+     * @param queue the queue to consume from.
      * 
      * @param ackMode the acknowledgement mode to use (@see
      * AckMode)
@@ -287,11 +287,11 @@ class Channel : private sys::Runnable
     /**
      * Publishes (i.e. sends a message to the broker).
      * 
-     * @param msg the message to publish
+     * @param msg the message to publish.
      * 
-     * @param exchange the exchange to publish the message to
+     * @param exchange the exchange to publish the message to.
      * 
-     * @param routingKey the routing key to publish with
+     * @param routingKey the routing key to publish with.
      * 
      * @param mandatory if true and the exchange to which this
      * publish is directed has no matching bindings, the message
diff --git a/cpp/src/qpid/client/Connection.h b/cpp/src/qpid/client/Connection.h
index d24809b31e..0ddd383381 100644
--- a/cpp/src/qpid/client/Connection.h
+++ b/cpp/src/qpid/client/Connection.h
@@ -40,7 +40,7 @@ namespace qpid {
 namespace client {
 
 /**
- * \defgroup clientapi Application API for an AMQP client
+ * \defgroup clientapi Application API for an AMQP client.
  */
 
 /**
@@ -66,14 +66,14 @@ class Connection
      * Creates a connection object, but does not open the
      * connection.  
      * 
-     * @param _version the version of the protocol to connect with
+     * @param _version the version of the protocol to connect with.
      *
      * @param debug turns on tracing for the connection
      * (i.e. prints details of the frames sent and received to std
-     * out). Optional and defaults to false.
+     * out). Optional. Defaults to false.
      * 
      * @param max_frame_size the maximum frame size that the
-     * client will accept. Optional and defaults to 65535.
+     * client will accept. Optional. Defaults to 65535.
      */
     Connection(bool debug = false, uint32_t max_frame_size = 65535,
                framing::ProtocolVersion=framing::highestProtocolVersion);
@@ -83,15 +83,15 @@ class Connection
     /**
      * Opens a connection to a broker.
      * 
-     * @param host the host on which the broker is running
+     * @param host the host on which the broker is running.
      * 
-     * @param port the port on the which the broker is listening
+     * @param port the port on the which the broker is listening.
      * 
-     * @param uid the userid to connect with
+     * @param uid the userid to connect with.
      * 
      * @param pwd the password to connect with (currently SASL
      * PLAIN is the only authentication method supported so this
-     * is sent in clear text)
+     * is sent in clear text).
      * 
      * @param virtualhost the AMQP virtual host to use (virtual
      * hosts, where implemented(!), provide namespace partitioning
@@ -103,7 +103,7 @@ class Connection
               const std::string& virtualhost = "/");
 
     /**
-     * Close the connection
+     * Close the connection.
      *
      * Any further use of this connection (without reopening it) will
      * not succeed.
@@ -113,7 +113,7 @@ class Connection
     /**
      * Associate a Channel with this connection and open it for use.
      *
-     * In AMQP channels are like multi-plexed 'sessions' of work over
+     * In AMQP, channels are like multiplexed 'sessions' of work over
      * a connection. Almost all the interaction with AMQP is done over
      * a channel.
      * 
@@ -129,7 +129,7 @@ class Connection
      *
      *@param detachedLifetime: A session may be detached from its
      * channel, either by calling Session::suspend() or because of a
-     * network failure. The session state is perserved for
+     * network failure. The session state is preserved for
      * detachedLifetime seconds to allow a call to resume(). After
      * that the broker may discard the session state. Default is 0,
      * meaning the session cannot be resumed.
diff --git a/cpp/src/qpid/client/Exchange.h b/cpp/src/qpid/client/Exchange.h
index 0640e4fe2c..239c131658 100644
--- a/cpp/src/qpid/client/Exchange.h
+++ b/cpp/src/qpid/client/Exchange.h
@@ -60,12 +60,12 @@ namespace client {
          */
 	static const std::string DIRECT_EXCHANGE;
         /**
-         * A topic exchange treat the key with which a queue is bound
+         * A topic exchange treats the key with which a queue is bound
          * as a pattern and routes all messages whose routing keys
          * match that pattern to the bound queue. The routing key for
          * a message must consist of zero or more alpha-numeric words
-         * delimited by dots. The pattern is of a similar form but *
-         * can be used to match excatly one word and # can be used to
+         * delimited by dots. The pattern is of a similar form, but *
+         * can be used to match exactly one word and # can be used to
          * match zero or more words.
          */
 	static const std::string TOPIC_EXCHANGE;
@@ -77,7 +77,7 @@ namespace client {
 	static const std::string HEADERS_EXCHANGE;
 
         /**
-         * The 'default' exchange, nameless and of type 'direct'. Has
+         * The 'default' exchange, nameless and of type 'direct', has
          * every declared queue bound to it by name.
          */
 	static const Exchange DEFAULT_EXCHANGE;
diff --git a/cpp/src/qpid/client/Message.h b/cpp/src/qpid/client/Message.h
index 864a16d9ce..3c22d202ee 100644
--- a/cpp/src/qpid/client/Message.h
+++ b/cpp/src/qpid/client/Message.h
@@ -30,7 +30,7 @@ namespace qpid {
 namespace client {
 
 /**
- * A representation of messages for sent or received through the
+ * A representation of messages sent or received through the
  * client api.
  *
  * \ingroup clientapi
diff --git a/cpp/src/qpid/client/MessageQueue.h b/cpp/src/qpid/client/MessageQueue.h
index e9b7a9fe58..ab6d351ba7 100644
--- a/cpp/src/qpid/client/MessageQueue.h
+++ b/cpp/src/qpid/client/MessageQueue.h
@@ -29,7 +29,7 @@ namespace qpid {
 namespace client {
 
 /**
- * A MessageListener implementation that simply queues up
+ * A MessageListener implementation that queues up
  * messages.
  *
  * \ingroup clientapi
diff --git a/cpp/src/qpid/client/Queue.h b/cpp/src/qpid/client/Queue.h
index 078e04c29e..baaa890464 100644
--- a/cpp/src/qpid/client/Queue.h
+++ b/cpp/src/qpid/client/Queue.h
@@ -36,19 +36,19 @@ namespace client {
      * that the queue exists or is created.
      * 
      * Queues hold messages and allow clients to consume
-     * (see Channel::consume()) or get (see Channel::get()) those messags. A
-     * queue receives messages by being bound to one or more Exchange;
-     * messages published to that exchange may then be routed to the
+     * (see Channel::consume()) or get (see Channel::get()) those messages. A
+     * queue receives messages by being bound to one or more Exchange.
+     * Messages published to that exchange may then be routed to the
      * queue based on the details of the binding and the type of the
      * exchange (see Channel::bind()).
      * 
      * Queues are identified by a name. They can be exclusive (in which
      * case they can only be used in the context of the connection
-     * over which they were declared, and are deleted when then
+     * over which they were declared, and are deleted when that
      * connection closes), or they can be shared. Shared queues can be
-     * auto deleted when they have no consumers.
+     * automatically deleted when they have no consumers.
      * 
-     * We use the term 'temporary queue' to refer to an exclusive
+     * The term 'temporary queue' refers to an exclusive
      * queue.
      */
     class Queue{
@@ -66,10 +66,10 @@ namespace client {
          */
 	Queue();
         /**
-         * Creates a shared, non-durable, queue with a given name,
-         * that will not be autodeleted.
+         * Creates a shared, non-durable queue with a given name,
+         * that will not be automatically deleted.
          * 
-         * @param name the name of the queue
+         * @param name the name of the queue.
          */
 	Queue(std::string name);
         /**
@@ -78,13 +78,13 @@ namespace client {
          * @param name the name of the queue
          * 
          * @param temp if true the queue will be a temporary queue, if
-         * false it will be shared and not autodeleted.
+         * false it will be shared and not automatically deleted.
          */
 	Queue(std::string name, bool temp);
         /**
-         * This constructor allows the autodelete, exclusive and
-         * durable propeties to be explictly set. Note however that if
-         * exclusive is true, autodelete has no meaning as exclusive
+         * This constructor allows the AutoDelete, Exclusive and
+         * Durable properties to be explictly set. Note however that if
+         * Exclusive is true, AutoDelete has no meaning as Exclusive
          * queues are always destroyed when the connection that
          * created them is closed.
          */
diff --git a/cpp/src/qpid/client/SessionBase.cpp b/cpp/src/qpid/client/SessionBase.cpp
index 5b9ff595ed..dfd0f62e7e 100644
--- a/cpp/src/qpid/client/SessionBase.cpp
+++ b/cpp/src/qpid/client/SessionBase.cpp
@@ -48,6 +48,8 @@ void SessionBase::flush()
     impl->sendFlush();
 }
 
+// FIXME aconway 2008-04-24: do we need to provide a non-synchronous version
+// of sync() or bool paramter to allow setting a sync point for a later wait?
 void SessionBase::sync()
 {
     ExecutionSyncBody b;
diff --git a/cpp/src/qpid/client/SessionBase.h b/cpp/src/qpid/client/SessionBase.h
index 61997244d2..aa61d2b49b 100644
--- a/cpp/src/qpid/client/SessionBase.h
+++ b/cpp/src/qpid/client/SessionBase.h
@@ -54,20 +54,17 @@ using framing::Uuid;
  * functions return immediately.
  *
  * ASYNC mode gives better performance for high-volume traffic, but
- * requires some additional caution:
+ * requires some additional caution.
  * 
  * Session functions return immediately. If the command causes an
  * exception on the broker, the exception will be thrown on a
  * <em>later</em> function call. 
  *
  * If you need to notify some extenal agent that some actions have
- * been taken (e.g. binding queues to exchanges), you must ensure that
- * the broker has completed the command. In synchronous mode this is
- * when the session method for the command returns. In asynchronous
- * mode you can call Session::sync(), to ensure that all the commands
- * are complete.
+ * been taken (e.g. binding queues to exchanges), you must call
+ * Session::sync() first to ensure that all the commands are complete.
  *
- * You can freely switch between modes by calling Session::setSynchronous()
+ * You can freely switch between modes by calling Session::setSynchronous().
  * 
  * @see Session::sync(), Session::setSynchronous()
  */
@@ -106,12 +103,12 @@ class SessionBase
 
     /**
      * In synchronous mode, wait for the broker's response before
-     * returning. Note this gives lower throughput than asynchronous
+     * returning. This gives lower throughput than asynchronous
      * mode.
      *
      * In asynchronous mode commands are sent without waiting
-     * for a respose (you can use the returned Completion object
-     * to wait for completion.)
+     * for a response (you can use the returned Completion object
+     * to wait for completion).
      * 
      * @see SynchronousMode
      */
@@ -121,7 +118,7 @@ class SessionBase
     SynchronousMode getSynchronous() const;
 
     /**
-     * Suspend the session, can be resumed on a different connection.
+     * Suspend the session, which can be resumed on a different connection.
      * @see Connection::resume()
      */
     void suspend();
diff --git a/cpp/src/qpid/framing/AccumulatedAck.h b/cpp/src/qpid/framing/AccumulatedAck.h
index a635d2ea04..ea78b797e0 100644
--- a/cpp/src/qpid/framing/AccumulatedAck.h
+++ b/cpp/src/qpid/framing/AccumulatedAck.h
@@ -43,17 +43,17 @@ namespace qpid {
             bool mergeable(const SequenceNumber& r) const;
         };
         /**
-         * Keeps an accumulated record of acked messages (by delivery
+         * Keeps an accumulated record of acknowledged messages (by delivery
          * tag).
          */
         class AccumulatedAck {
 	public:
             /**
-             * Everything up to this value has been acked.
+             * Everything up to this value has been acknowledged.
              */
             SequenceNumber mark;
             /**
-             * List of individually acked messages greater than the
+             * List of individually acknowledged messages greater than the
              * 'mark'.
              */
             std::list<Range> ranges;
diff --git a/cpp/src/qpid/framing/Blob.h b/cpp/src/qpid/framing/Blob.h
index dd86392e5b..8b304ba708 100644
--- a/cpp/src/qpid/framing/Blob.h
+++ b/cpp/src/qpid/framing/Blob.h
@@ -77,16 +77,16 @@ template <> struct BlobHelper<void> {
 };
 
 /**
- * A "blob" is a chunk of memory which can contain a single object at
- * a time arbitrary type, provided sizeof(T)<=blob.size(). Blob
+ * A Blob is a chunk of memory which can contain a single object at
+ * a time-arbitrary type, provided sizeof(T)<=blob.size(). Using Blobs
  * ensures proper construction and destruction of its contents,
  * and proper copying between Blobs, but nothing else.
  * 
- * In particular the user must ensure the blob is big enough for its
- * contents and must know the type of object in the blob to cast get().
+ * In particular you must ensure that the Blob is big enough for its
+ * contents and must know the type of object in the Blob to cast get().
  *
- * If BaseType is specified then only object that can be
- * safely static_cast to BaseType may be stored in the Blob.
+ * If BaseType is specified then only an object that can be
+ * static_cast to BaseType may be stored in the Blob.
  */
 template <size_t Size, class BaseType=void>
 class Blob
@@ -131,19 +131,19 @@ class Blob
     }
 
   public:
-    /** Construct an empty blob. */
+    /** Construct an empty Blob. */
     Blob() { initialize(); }
 
-    /** Copy a blob. */
+    /** Copy a Blob. */
     Blob(const Blob& b) { initialize(); assign(b); }
 
-    /** Construct from in_place constructor */
+    /** Construct from in_place constructor. */
     template<class InPlace>
     Blob(const InPlace & expr, typename EnableInPlace<InPlace>::type* =0) {
         initialize(); apply(expr);
     }
 
-    /** Construct by copying an objecct constructor */
+    /** Construct by copying an object constructor. */
     template<class T>
     Blob(const T & t, typename DisableInPlace<T>::type* =0) {
         initialize(); apply(in_place<T>(t));
@@ -151,7 +151,7 @@ class Blob
 
     ~Blob() { clear(); }
 
-    /** Assign from another blob. */
+    /** Assign from another Blob. */
     Blob& operator=(const Blob& b) {
         clear();
         assign(b);
@@ -170,13 +170,13 @@ class Blob
         clear(); apply(in_place<T>(x)); return *this;
     }
 
-    /** Get pointer to blob contents, returns 0 if empty. */
+    /** Get pointer to Blob contents, returns 0 if empty. */
     BaseType* get() { return  basePtr; }
 
-    /** Get pointer to blob contents, returns 0 if empty. */
+    /** Get pointer to Blob contents, returns 0 if empty. */
     const BaseType* get() const { return basePtr; }
 
-    /** Destroy the object in the blob making it empty. */
+    /** Destroy the object in the Blob making it empty. */
     void clear() {
         void (*oldDestroy)(void*) = destroy; 
         initialize();
diff --git a/cpp/src/qpid/framing/BodyHolder.h b/cpp/src/qpid/framing/BodyHolder.h
index 65029e5675..f843961a32 100644
--- a/cpp/src/qpid/framing/BodyHolder.h
+++ b/cpp/src/qpid/framing/BodyHolder.h
@@ -47,14 +47,14 @@ class BodyHolder : public RefCounted
     BodyHolder(const AMQBody& b) { setBody(b); }
     BodyHolder(ClassId c, MethodId m) { setMethod(c,m); }
 
-    /** Construct from an in_place constructor expression */
+    /** Construct from an in_place constructor expression. */
     template <class InPlace>
     BodyHolder(const InPlace& ip, typename EnableInPlace<InPlace>::type* =0)
         : blob(ip) {}
 
     void setBody(const AMQBody& b);
 
-    /** Assign from an in_place constructor expression */
+    /** Assign from an in_place constructor expression. */
     template <class InPlace>
     typename EnableInPlace<InPlace,BodyHolder&>::type
     operator=(const InPlace& ip) { blob=ip; return *this; }
diff --git a/cpp/src/qpid/framing/FieldValue.h b/cpp/src/qpid/framing/FieldValue.h
index d7efc4d22d..a4c20bf415 100644
--- a/cpp/src/qpid/framing/FieldValue.h
+++ b/cpp/src/qpid/framing/FieldValue.h
@@ -35,7 +35,7 @@ namespace qpid {
 namespace framing {
 
 /**
- * Exception that is base exception for all field table errors 
+ * Exception that is the base exception for all field table errors.
  * 
  * \ingroup clientapi
  */
diff --git a/cpp/src/qpid/framing/FrameDefaultVisitor.h b/cpp/src/qpid/framing/FrameDefaultVisitor.h
index 07e1d6d997..bd676960bf 100644
--- a/cpp/src/qpid/framing/FrameDefaultVisitor.h
+++ b/cpp/src/qpid/framing/FrameDefaultVisitor.h
@@ -31,10 +31,10 @@
 namespace qpid {
 namespace framing {
 /**
- * Visitor for all concrete frame body types, combines
+ * Visitor for all concrete frame body types, which combines
  * AMQBodyConstVisitor and MethodBodyDefaultVisitor.
  * 
- * Derived classes may override visit methods to specify actions.
+ * Derived classes can override visit methods to specify actions.
  * Derived classes must override defaultVisit(), which is called
  * for any non-overridden visit functions.
  *
diff --git a/cpp/src/qpid/framing/FramingContent.h b/cpp/src/qpid/framing/FramingContent.h
index 9315a7716f..36f5d641b2 100644
--- a/cpp/src/qpid/framing/FramingContent.h
+++ b/cpp/src/qpid/framing/FramingContent.h
@@ -31,7 +31,7 @@ class Buffer;
 enum discriminator_types { INLINE = 0, REFERENCE = 1 };
 
 /**
- * A representation of the AMQP 'content' data type (used for message
+ * A representation of the AMQP Content data type (used for message
  * bodies) which can hold inline data or a reference.
  */
 class Content
diff --git a/cpp/src/qpid/framing/Invoker.h b/cpp/src/qpid/framing/Invoker.h
index 6c2b972c13..4f1cf7c331 100644
--- a/cpp/src/qpid/framing/Invoker.h
+++ b/cpp/src/qpid/framing/Invoker.h
@@ -58,7 +58,7 @@ class Invoker: public MethodBodyDefaultVisitor, protected StructHelper
 };
 
 /**
- * Invoke on an invocable object.
+ * Invoke an invocable object.
  * Invocable classes must provide a nested type Invoker.
  */
 template <class Invocable>
@@ -69,7 +69,7 @@ Invoker::Result invoke(Invocable& target, const AMQMethodBody& body) {
 }
 
 /**
- * Invoke on an invocable object.
+ * Invoke an invocable object.
  * Invocable classes must provide a nested type Invoker.
  */
 template <class Invocable>
diff --git a/cpp/src/qpid/framing/SessionState.h b/cpp/src/qpid/framing/SessionState.h
index 066bece003..4b3f704dda 100644
--- a/cpp/src/qpid/framing/SessionState.h
+++ b/cpp/src/qpid/framing/SessionState.h
@@ -36,7 +36,7 @@ namespace framing {
 
 /**
  * Session state common to client and broker.
- * Stores replay frames, implements session ack/resume protcools.
+ * Stores replay frames, implements session ack/resume protocols.
  *
  * A SessionState is always associated with an _open_ session (attached or
  * suspended) it is destroyed when the session is closed.
@@ -50,16 +50,16 @@ class SessionState
     /** States of a session. */
     enum State {
         SUSPENDED, ///< Suspended, detached from any channel.
-        RESUMING, ///< Resuming: waiting for initial ack from peer.
+        RESUMING, ///< Resuming, waiting for an initial ack from a peer.
         ATTACHED ///< Attached to channel and operating normally.
     };
 
     /**
      *Create a newly opened active session.
-     *@param ackInterval send/solicit an ack whenever N unacked frames
+     *@param ackInterval send/solicit an ack whenever N unacknowledged frames
      * have been received/sent.
      * 
-     * N=0 disables voluntary send/solict ack.
+     * N=0 disables voluntary send/solicit ack.
      */
     SessionState(uint32_t ackInterval, bool enableReplay = true, const framing::Uuid& id=framing::Uuid(true));
 
@@ -75,7 +75,7 @@ class SessionState
     /** Received incoming L3 frame.
      * @return SequenceNumber if an ack should be sent, empty otherwise.
      * SessionState assumes that acks are sent whenever it returns
-     * a seq. number.
+     * a sequence number.
      */
     boost::optional<SequenceNumber> received(const AMQFrame&);
 
@@ -100,9 +100,9 @@ class SessionState
      *@returns sequence number to ack immediately.  */
     SequenceNumber resuming();
 
-    /** About to send an unscheduled ack, e.g. to respond to a solicit-ack.
+    /** About to send an unscheduled ack, for example, responding to a solicit-ack.
      * 
-     * Note: when received() returns a sequence number this function
+     * Note: when received() returns a sequence number, this function
      * should not be called. SessionState assumes that the ack is sent
      * every time received() returns a sequence number.
      */
diff --git a/cpp/src/qpid/framing/TemplateVisitor.h b/cpp/src/qpid/framing/TemplateVisitor.h
index 8c719e5110..d6d59603f7 100644
--- a/cpp/src/qpid/framing/TemplateVisitor.h
+++ b/cpp/src/qpid/framing/TemplateVisitor.h
@@ -27,7 +27,7 @@ namespace qpid {
 namespace framing {
 
 /**
- * Metafunction to generate a visitor class derived from Base with a
+ * Metafunction to generate a visitor class derived from Base, with a
  * visit for each type in TypeList calling functor F. TypeList may be
  * any boost::mpl type collection e.g. mpl::list. 
  *
diff --git a/cpp/src/qpid/framing/Uuid.h b/cpp/src/qpid/framing/Uuid.h
index bce18f55b3..f23590ebdc 100644
--- a/cpp/src/qpid/framing/Uuid.h
+++ b/cpp/src/qpid/framing/Uuid.h
@@ -41,19 +41,19 @@ struct Uuid : public boost::array<uint8_t, 16> {
     /** If unique is true, generate a unique ID else a null ID. */
     Uuid(bool unique=false) { if (unique) generate(); else clear(); }
 
-    /** Copy from 16 bytes of data */
+    /** Copy from 16 bytes of data. */
     Uuid(const uint8_t* data) { assign(data); }
 
-    /** Copy from 16 bytes of data */
+    /** Copy from 16 bytes of data. */
     void assign(const uint8_t* data) { uuid_copy(c_array(), data); }
     
-    /** Set to a new unique identifier */
+    /** Set to a new unique identifier. */
     void generate() { uuid_generate(c_array()); }
 
-    /** Set to all zeros */
+    /** Set to all zeros. */
     void clear() { uuid_clear(c_array()); }
     
-    /** Test for null (all zeros) */
+    /** Test for null (all zeros). */
     bool isNull() const { return uuid_is_null(data()); }
 
     // Default op= and copy ctor are fine.
@@ -63,7 +63,7 @@ struct Uuid : public boost::array<uint8_t, 16> {
     
     void decode(framing::Buffer& buf);
 
-    /** String value in format 1b4e28ba-2fa1-11d2-883f-b9a761bde3fb */
+    /** String value in format 1b4e28ba-2fa1-11d2-883f-b9a761bde3fb. */
     std::string str() const;
 
     template <class S> void serialize(S& s) {
@@ -71,10 +71,10 @@ struct Uuid : public boost::array<uint8_t, 16> {
     }
 };
 
-/** Print in format 1b4e28ba-2fa1-11d2-883f-b9a761bde3fb */
+/** Print in format 1b4e28ba-2fa1-11d2-883f-b9a761bde3fb. */
 std::ostream& operator<<(std::ostream&, const Uuid&);
 
-/** Read from format 1b4e28ba-2fa1-11d2-883f-b9a761bde3fb */
+/** Read from format 1b4e28ba-2fa1-11d2-883f-b9a761bde3fb. */
 std::istream& operator>>(std::istream&, Uuid&);
 
 }} // namespace qpid::framing
diff --git a/cpp/src/qpid/framing/Visitor.h b/cpp/src/qpid/framing/Visitor.h
index 9753b21954..759ee65914 100644
--- a/cpp/src/qpid/framing/Visitor.h
+++ b/cpp/src/qpid/framing/Visitor.h
@@ -30,10 +30,10 @@ namespace framing {
 
 /** @file Generic visitor pattern. */
 
-/** visit() interface for type T (optional return type R, default void.)
+/** visit() interface for type T (optional return type R, default is void.)
  * To create  a visitor for a set of types T1, T2 ... do this:
  * struct MyVisitor : public Visit<T1>, public Visit<T2> ... {};
- *@param T Type to visit, must be forward declared, need not be defined.
+ *@param T Type to visit. This must be forward declared, and need not be defined.
  */
 template <class T, class R=void> struct Visit {
     typedef R ReturnType;
@@ -56,7 +56,7 @@ template <class T, class R=void> struct Visit {
  * @endcode
  * @param visitor name of the generated visitor class.
  * @param bases a sequence of visitable types in the form (T1)(T2)...
- * The odd parenthesized notation is due to quirks of the preprocesser.
+ * Any parenthesized notations are due to quirks of the preprocesser.
  */
 #define QPID_VISITOR(visitor,types) \
     BOOST_PP_SEQ_FOR_EACH(QPID_VISITOR_DECL, _, types) \
@@ -64,8 +64,8 @@ template <class T, class R=void> struct Visit {
     BOOST_PP_SEQ_FOR_EACH(QPID_VISITOR_BASE, _, BOOST_PP_SEQ_TAIL(types)) \
     {}
 
-/** Root class for hierarchy of objects visitable by Visitor V.
- * Defines virtual accept()
+/** The root class for the hierarchy of objects visitable by Visitor V.
+ * Defines virtual accept().
  */
 template <class V, class R=void>
 struct VisitableRoot {
@@ -75,8 +75,9 @@ struct VisitableRoot {
     virtual R accept(V& v) = 0;
 };
 
-/** Base class for concrete visitable classes, implements accept().
- * @param T type of visitable class (CRTP)
+/** The base class for concrete visitable classes.
+ * Implements accept().
+ * @param T type of visitable class (CRTP).
  * @param Base base class to inherit from.
  */
 template <class T, class Base>
diff --git a/cpp/src/qpid/framing/amqp_types.h b/cpp/src/qpid/framing/amqp_types.h
index 943970cc56..8b10aa3069 100644
--- a/cpp/src/qpid/framing/amqp_types.h
+++ b/cpp/src/qpid/framing/amqp_types.h
@@ -22,7 +22,7 @@
  */
 
 /** \file
- * Type definitions and forward declarations of all types used to
+ * Definitions and forward declarations of all types used 
  * in AMQP messages.
  */
 
diff --git a/cpp/src/qpid/framing/amqp_types_full.h b/cpp/src/qpid/framing/amqp_types_full.h
index da7bdc876d..1ab8777896 100644
--- a/cpp/src/qpid/framing/amqp_types_full.h
+++ b/cpp/src/qpid/framing/amqp_types_full.h
@@ -20,12 +20,12 @@
  */
 
 /** \file
- * Type definitions and full declarations of all types used to
+ * Definitions and full declarations of all types used
  * in AMQP messages.
  *
- * Its better to include amqp_types.h in another header instead of this file
+ * It's better to include amqp_types.h in another header instead of this file
  * unless the header actually needs the full declarations. Including
- * full declarations when forward declarations would do increases compile
+ * full declarations when forward declarations would increase compile
  * times.
  */
 
diff --git a/cpp/src/qpid/framing/frame_functors.h b/cpp/src/qpid/framing/frame_functors.h
index d915a270c2..8ae3d15b4f 100644
--- a/cpp/src/qpid/framing/frame_functors.h
+++ b/cpp/src/qpid/framing/frame_functors.h
@@ -75,7 +75,7 @@ public:
 };
 
 /**
- * Sends a copy of the frame its applied to to the specified handler
+ * Sends to the specified handler a copy of the frame it is applied to.
  */
 class Relay
 {
diff --git a/cpp/src/qpid/framing/variant.h b/cpp/src/qpid/framing/variant.h
index ceaed2c529..8e13063385 100644
--- a/cpp/src/qpid/framing/variant.h
+++ b/cpp/src/qpid/framing/variant.h
@@ -21,7 +21,7 @@
  *
  */
 
-/**@file Tools for using boost::variant */
+/**@file Tools for using boost::variant. */
 
 
 #include <boost/variant.hpp>
@@ -30,8 +30,8 @@ namespace qpid {
 namespace framing {
 class Buffer;
 
-/** boost::static_visitor that throws exception if variant contains blank.
- * Sublclasses need to have a using() declaration, can be generated
+/** boost::static_visitor that throws an exception if variant contains a blank.
+ * Subclasses need to have a using() declaration, which can be generated
  * with QPID_USING_NOBLANK(R)
  */
 template <class R=void>
@@ -48,7 +48,7 @@ struct NoBlankVisitor : public boost::static_visitor<R> {
 }} // qpid::framing
 
 
-/** Generate using statement needed in visitors inheriting NoBlankVisitor
+/** Generate a using statement, needed in visitors inheriting NoBlankVisitor
  *  @param R return type.
  */
 #define QPID_USING_NOBLANK(R) using ::qpid::framing::NoBlankVisitor<R>::operator()
@@ -62,13 +62,13 @@ template <class R> struct ConvertVisitor : public NoBlankVisitor<R> {
     template <class T> R operator()(T& t) const { return t; }
 };
 
-/** Convert address of variant value to type R. */
+/** Convert the address of variant value to type R. */
 template <class R> struct AddressVisitor : public NoBlankVisitor<R> {
     QPID_USING_NOBLANK(R);
     template <class T> R operator()(T& t) const { return &t; }
 };
 
-/** Apply a visitor to the nested variant in a variant of variants */
+/** Apply a visitor to the nested variant.*/
 template<class V>
 struct ApplyVisitor : public NoBlankVisitor<typename V::result_type> {
     QPID_USING_NOBLANK(typename V::result_type);