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

15 files changed, 60 insertions, 59 deletions

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);