qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jr...@apache.org
Subject [2/3] qpid-proton git commit: PROTON-1109: Improve C++ binding documentation
Date Tue, 26 Jan 2016 05:17:37 GMT
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/container.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/container.hpp b/proton-c/bindings/cpp/include/proton/container.hpp
index 8e907b7..8b33ca4 100644
--- a/proton-c/bindings/cpp/include/proton/container.hpp
+++ b/proton-c/bindings/cpp/include/proton/container.hpp
@@ -21,6 +21,7 @@
  * under the License.
  *
  */
+
 #include "proton/duration.hpp"
 #include "proton/export.hpp"
 #include "proton/pn_unique_ptr.hpp"
@@ -43,76 +44,99 @@ class handler;
 class task;
 class container_impl;
 
-/**
- * Top level container for connections and other objects, runs the event loop.
- *
- * Note that by default, links belonging to the container have generated link-names
- * of the form
- */
+/// A top-level container of connections, sessions, and links.
+///
+/// A container gives a unique identity to each communicating peer. It
+/// is often a process-level object.
+
+/// It serves as an entry point to the API, allowing connections and
+/// links to be established. It can be supplied with an event handler
+/// in order to intercept important messaging events, such as newly
+/// received messages or newly issued link credit for sending
+/// messages.
 class container {
   public:
-    /// Container ID should be unique within your system.
-    /// By default a random ID is generated.
+    /// Create a container.
+    ///
+    /// Container ID should be unique within your system. By default a
+    /// random ID is generated.
     PN_CPP_EXTERN container(const std::string& id="");
 
-    /// Container ID should be unique within your system. By default a random ID is generated.
+    /// Create a container with an event handler.
+    ///
+    /// Container ID should be unique within your system. By default a
+    /// random ID is generated.
     PN_CPP_EXTERN container(handler& mhandler, const std::string& id=std::string());
 
     PN_CPP_EXTERN ~container();
 
-    /** Locally open a connection @see connection::open  */
-    PN_CPP_EXTERN connection connect(const proton::url&, const connection_options &opts = connection_options());
+    /// Open a connection to `url`.
+    PN_CPP_EXTERN connection connect(const proton::url&,
+                                     const connection_options &opts = connection_options());
 
-    /** Listen on url host and port for incoming connections. */
-    PN_CPP_EXTERN acceptor listen(const proton::url&, const connection_options &opts = connection_options());
+    /// Listen on `url` for incoming connections.
+    PN_CPP_EXTERN acceptor listen(const proton::url&,
+                                  const connection_options &opts = connection_options());
 
-    /** Run the event loop, return when all connections and acceptors are closed. */
+    /// Start processing events. It returns when all connections and
+    /// acceptors are closed.
     PN_CPP_EXTERN void run();
 
-    /** Open a new connection to url and create a sender with target=url.path().
-        Any supplied link or connection options will override the container's
-        template options. */
-    PN_CPP_EXTERN sender open_sender(const proton::url &, const proton::link_options &l = proton::link_options(),
+    /// Open a connection to `url` and open a sender for `url.path()`.
+    /// Any supplied link or connection options will override the
+    /// container's template options.
+    PN_CPP_EXTERN sender open_sender(const proton::url &,
+                                     const proton::link_options &l = proton::link_options(),
                                      const connection_options &c = connection_options());
 
-    /** Create a receiver on a new connection with source=url.path(). Any
-        supplied link or connection options will override the container's
-        template options. */
-    PN_CPP_EXTERN receiver open_receiver(const url &, const proton::link_options &l = proton::link_options(),
+    /// Open a connection to `url` and open a receiver for
+    /// `url.path()`.  Any supplied link or connection options will
+    /// override the container's template options.
+    PN_CPP_EXTERN receiver open_receiver(const url &,
+                                         const proton::link_options &l = proton::link_options(),
                                          const connection_options &c = connection_options());
 
-    /// Identifier for the container
+    /// A unique identifier for the container.
     PN_CPP_EXTERN std::string id() const;
 
+    /// @cond INTERNAL
+
+    /// XXX remove
     /// The reactor associated with this container.
     PN_CPP_EXTERN class reactor reactor() const;
 
-    // Schedule a timer task event in delay milliseconds.
+    /// XXX settle some API questions
+    /// Schedule a timer task event in delay milliseconds.
     PN_CPP_EXTERN task schedule(int delay, handler *h = 0);
 
-    /** Copy the connection options to a template which will be
-        applied to subsequent outgoing connections.  These are applied first
-        and overriden by additional connection options provided in
-        other methods */
+    /// @endcond
+
+    /// Copy the connection options to a template which will be
+    /// applied to subsequent outgoing connections.  These are applied
+    /// first and overriden by additional connection options provided
+    /// in other methods.
     PN_CPP_EXTERN void client_connection_options(const connection_options &);
 
-    /** Copy the connection options to a template which will be
-        applied to incoming connections.  These are applied before the
-        first open event on the connection. */
+    /// Copy the connection options to a template which will be
+    /// applied to incoming connections.  These are applied before the
+    /// first open event on the connection.
     PN_CPP_EXTERN void server_connection_options(const connection_options &);
 
-    /** Copy the link options to a template applied to new links created and
-        opened by this container.  They are applied before the open event on the
-        link and may be overriden by link options in other methods. */
+    /// Copy the link options to a template applied to new links
+    /// created and opened by this container.  They are applied before
+    /// the open event on the link and may be overriden by link
+    /// options in other methods.
     PN_CPP_EXTERN void link_options(const link_options &);
 
-
   private:
     pn_unique_ptr<container_impl> impl_;
+
+    /// @cond INTERNAL
     friend class connector;
-  friend class link;
+    friend class link;
+    /// @endcond
 };
 
 }
 
-#endif  /*!PROTON_CPP_CONTAINER_H*/
+#endif // PROTON_CPP_CONTAINER_H

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/data.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/data.hpp b/proton-c/bindings/cpp/include/proton/data.hpp
index c9f0a08..09cca58 100644
--- a/proton-c/bindings/cpp/include/proton/data.hpp
+++ b/proton-c/bindings/cpp/include/proton/data.hpp
@@ -1,5 +1,6 @@
 #ifndef DATA_H
 #define DATA_H
+
 /*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
@@ -19,7 +20,8 @@
  * under the License.
  */
 
-///@cond INTERNAL
+/// @cond INTERNAL
+/// XXX remove
 
 #include "proton/decoder.hpp"
 #include "proton/encoder.hpp"
@@ -34,10 +36,9 @@ namespace proton {
 
 class data;
 
-/**@internal
- * Holds a sequence of AMQP values, allows inserting and extracting via encoder() and decoder().
- * Cannot be directly instantiated, use `value`
- */
+/// Holds a sequence of AMQP values, allows inserting and extracting
+/// via encoder() and decoder().  Cannot be directly instantiated, use
+/// `value`.
 class data : public object<pn_data_t> {
   public:
     data(pn_data_t* d=0) : object<pn_data_t>(d) {}
@@ -98,6 +99,6 @@ class data : public object<pn_data_t> {
 
 }
 
-///@endcond
+/// @endcond
 
 #endif // DATA_H

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/decoder.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/decoder.hpp b/proton-c/bindings/cpp/include/proton/decoder.hpp
index fdd2f22..3dab9c9 100644
--- a/proton-c/bindings/cpp/include/proton/decoder.hpp
+++ b/proton-c/bindings/cpp/include/proton/decoder.hpp
@@ -19,7 +19,8 @@
  * under the License.
  */
 
-///@cond INTERNAL
+/// @cond INTERNAL
+/// XXX change namespace, review better
 
 #include "proton/error.hpp"
 #include "proton/type_traits.hpp"
@@ -396,6 +397,7 @@ template <class K, class T, class C, class A> decoder operator>>(decoder d, std:
 #endif // PN_NO_CONTAINER_CONVERT
 
 }
-///@endcond
+
+/// @endcond
 
 #endif // DECODER_H

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/delivery.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/delivery.hpp b/proton-c/bindings/cpp/include/proton/delivery.hpp
index a05347b..c4e6243 100644
--- a/proton-c/bindings/cpp/include/proton/delivery.hpp
+++ b/proton-c/bindings/cpp/include/proton/delivery.hpp
@@ -1,4 +1,3 @@
-
 #ifndef PROTON_CPP_DELIVERY_H
 #define PROTON_CPP_DELIVERY_H
 
@@ -22,6 +21,7 @@
  * under the License.
  *
  */
+
 #include "proton/export.hpp"
 #include "proton/object.hpp"
 
@@ -30,94 +30,95 @@
 
 namespace proton {
 
-/** delivery status of a message */
+/// A message transfer.  Every delivery exists within the context of a
+/// proton::link.  A delivery attempt can fail. As a result, a
+/// particular message may correspond to multiple deliveries.
 class delivery : public object<pn_delivery_t> {
   public:
+    /// @cond INTERNAL
     delivery(pn_delivery_t* d=0) : object<pn_delivery_t>(d) {}
+    /// @endcond
 
-    /** Delivery state of a message */
+    /// Delivery state values.
     enum state {
-        NONE = 0, ///< Unknown state
+        NONE = 0,               ///< Unknown state
         RECEIVED = PN_RECEIVED, ///< Received but not yet settled
         ACCEPTED = PN_ACCEPTED, ///< Settled as accepted
         REJECTED = PN_REJECTED, ///< Settled as rejected
         RELEASED = PN_RELEASED, ///< Settled as released
         MODIFIED = PN_MODIFIED  ///< Settled as modified
-    };  // AMQP spec 3.4 delivery State
+    }; // AMQP spec 3.4 delivery State
 
-    /** Return true if the delivery has been settled. */
+    /// @cond INTERNAL
+    /// XXX settle how much of this we need to expose
+    
+    /// Return true if the delivery has been settled.
     PN_CPP_EXTERN bool settled() const;
 
-    /** Settle the delivery, informs the remote end. */
+    /// Settle the delivery; informs the remote end.
     PN_CPP_EXTERN void settle();
 
-    /** Set the local state of the delivery. */
+    /// Set the local state of the delivery.
     PN_CPP_EXTERN void update(delivery::state state);
 
-    /** update and settle a delivery with the given delivery::state */
+    /// Update and settle a delivery with the given delivery::state
     PN_CPP_EXTERN void settle(delivery::state s);
 
-    /** settle with ACCEPTED state */
+    /// @endcond
+
+    /// Settle with ACCEPTED state
     PN_CPP_EXTERN void accept() { settle(ACCEPTED); }
 
-    /** settle with REJECTED state */
+    /// Settle with REJECTED state
     PN_CPP_EXTERN void reject() { settle(REJECTED); }
 
-    /** settle with REJECTED state */
+    /// Settle with RELEASED state
     PN_CPP_EXTERN void release() { settle(RELEASED); }
 
-    /** settle with MODIFIED state */
+    /// Settle with MODIFIED state
     PN_CPP_EXTERN void modify() { settle(MODIFIED); }
 
-    /**
-     * Check if a delivery is readable.
-     *
-     * A delivery is considered readable if it is the current delivery on
-     * an incoming link.
-     */
+    /// @cond INTERNAL
+    /// XXX who needs this?
+    
+    /// Check if a delivery is readable.
+    ///
+    /// A delivery is considered readable if it is the current delivery on
+    /// an incoming link.
     PN_CPP_EXTERN bool partial() const;
 
-    /**
-     * Check if a delivery is writable.
-     *
-     * A delivery is considered writable if it is the current delivery on
-     * an outgoing link, and the link has positive credit.
-     */
+    /// Check if a delivery is writable.
+    ///
+    /// A delivery is considered writable if it is the current delivery on
+    /// an outgoing link, and the link has positive credit.
     PN_CPP_EXTERN bool writable() const;
 
-    /**
-     * Check if a delivery is readable.
-     *
-     * A delivery is considered readable if it is the current delivery on
-     * an incoming link.
-     */
+    /// Check if a delivery is readable.
+    ///
+    /// A delivery is considered readable if it is the current
+    /// delivery on an incoming link.
     PN_CPP_EXTERN bool readable() const;
 
-    /**
-     * Check if a delivery is updated.
-     *
-     * A delivery is considered updated whenever the peer communicates a
-     * new disposition for the delivery. Once a delivery becomes updated,
-     * it will remain so until clear() is called.
-     */
+    /// Check if a delivery is updated.
+    ///
+    /// A delivery is considered updated whenever the peer
+    /// communicates a new disposition for the delivery. Once a
+    /// delivery becomes updated, it will remain so until clear() is
+    /// called.
     PN_CPP_EXTERN bool updated() const;
 
-    /**
-     * Clear the updated flag for a delivery.
-     */
+    /// Clear the updated flag for a delivery.
     PN_CPP_EXTERN void clear();
 
-    /**
-     * Get the remote disposition state for a delivery.
-     */
-    PN_CPP_EXTERN state remote_state() const;
-
-    /**
-     * Get the size of the current delivery
-     */
+    /// Get the size of the current delivery.
     PN_CPP_EXTERN size_t pending() const;
+
+    /// @endcond
+
+    /// Get the remote state for a delivery.
+    PN_CPP_EXTERN state remote_state() const;
 };
 
 }
 
-#endif  /*!PROTON_CPP_DELIVERY_H*/
+#endif // PROTON_CPP_DELIVERY_H

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/duration.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/duration.hpp b/proton-c/bindings/cpp/include/proton/duration.hpp
index 1726701..200064d 100644
--- a/proton-c/bindings/cpp/include/proton/duration.hpp
+++ b/proton-c/bindings/cpp/include/proton/duration.hpp
@@ -28,17 +28,21 @@
 
 namespace proton {
 
-/** Duration in milliseconds. */
-class duration : public comparable<duration>
-{
+/// A span of time in milliseconds.
+class duration : public comparable<duration> {
   public:
+    /// @cond INTERNAL
+    /// XXX public and mutable?
     uint64_t milliseconds;
+    /// @endcond
+
+    /// Create a duration.
     explicit duration(uint64_t ms = 0) : milliseconds(ms) {}
 
-    PN_CPP_EXTERN static const duration FOREVER; ///< Wait for ever
+    PN_CPP_EXTERN static const duration FOREVER;   ///< Wait for ever
     PN_CPP_EXTERN static const duration IMMEDIATE; ///< Don't wait at all
-    PN_CPP_EXTERN static const duration SECOND; ///< One second
-    PN_CPP_EXTERN static const duration MINUTE; ///< One minute
+    PN_CPP_EXTERN static const duration SECOND;    ///< One second
+    PN_CPP_EXTERN static const duration MINUTE;    ///< One minute
 };
 
 inline bool operator<(duration x, duration y) { return x.milliseconds < y.milliseconds; }
@@ -49,6 +53,7 @@ inline duration operator*(amqp_ulong n, duration d) { return d * n; }
 
 inline amqp_timestamp operator+(amqp_timestamp ts, duration d) { return amqp_timestamp(ts.milliseconds+d.milliseconds); }
 inline amqp_timestamp operator+(duration d, amqp_timestamp ts) { return ts + d; }
+
 }
 
-#endif  /*!PROTON_CPP_DURATION_H*/
+#endif // PROTON_CPP_DURATION_H

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/encoder.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/encoder.hpp b/proton-c/bindings/cpp/include/proton/encoder.hpp
index c2d683e..1876412 100644
--- a/proton-c/bindings/cpp/include/proton/encoder.hpp
+++ b/proton-c/bindings/cpp/include/proton/encoder.hpp
@@ -1,5 +1,6 @@
 #ifndef ENCODER_H
 #define ENCODER_H
+
 /*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
@@ -19,7 +20,8 @@
  * under the License.
  */
 
-///@cond INTERNAL
+/// @cond INTERNAL
+/// XXX change namespace, review better
 
 #include "proton/error.hpp"
 #include "proton/types.hpp"
@@ -42,8 +44,8 @@
 
 #endif // PN_NO_CONTAINER_CONVERT
 
-///@file
-///@internal
+/// @file
+/// @internal
 
 struct pn_data_t;
 
@@ -62,6 +64,7 @@ template<class T, type_id A> struct cref {
     cref(const T& v) : value(v) {}
     const T& value;
 };
+
 template <class T, type_id A> const type_id cref<T, A>::type = A;
 
 /**
@@ -264,8 +267,9 @@ template <class K, class T, class C, class A> encoder operator<<(encoder e, cons
 #endif // PN_HAS_CPP11
 
 #endif // PN_NO_CONTAINER_CONVERT
+
 }
 
-///@endcond
+/// @endcond
 
 #endif // ENCODER_H

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/endpoint.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/endpoint.hpp b/proton-c/bindings/cpp/include/proton/endpoint.hpp
index 832548a..fd698b0 100644
--- a/proton-c/bindings/cpp/include/proton/endpoint.hpp
+++ b/proton-c/bindings/cpp/include/proton/endpoint.hpp
@@ -27,42 +27,42 @@
 
 namespace proton {
 
-/** endpoint is a base class for session, connection and link */
-class endpoint
-{
+/// The base class for session, connection, and link.
+class endpoint {
   public:
-    /** state is a bit mask of state_bit values.
-     *
-     * A state mask is matched against an endpoint as follows: If the state mask
-     * contains both local and remote flags, then an exact match against those
-     * flags is performed. If state contains only local or only remote flags,
-     * then a match occurs if any of the local or remote flags are set
-     * respectively.
-     *
-     * @see connection::links, connection::sessions
-     */
+    /// A bit mask of state bit values.
+    ///
+    /// A state mask is matched against an endpoint as follows: If the
+    /// state mask contains both local and remote flags, then an exact
+    /// match against those flags is performed. If state contains only
+    /// local or only remote flags, then a match occurs if any of the
+    /// local or remote flags are set respectively.
+    ///
+    /// @see connection::find_links, connection::find_sessions
     typedef int state;
 
-    /// endpoint state bit values @{
-    PN_CPP_EXTERN static const state LOCAL_UNINIT;    ///< Local endpoint is un-initialized
-    PN_CPP_EXTERN static const state REMOTE_UNINIT;   ///< Remote endpoint is un-initialized
-    PN_CPP_EXTERN static const state LOCAL_ACTIVE;    ///< Local endpoint is active
-    PN_CPP_EXTERN static const state REMOTE_ACTIVE;   ///< Remote endpoint is active
-    PN_CPP_EXTERN static const state LOCAL_CLOSED;    ///< Local endpoint has been closed
-    PN_CPP_EXTERN static const state REMOTE_CLOSED;   ///< Remote endpoint has been closed
-    PN_CPP_EXTERN static const state LOCAL_MASK;      ///< Mask including all LOCAL_ bits (UNINIT, ACTIVE, CLOSED)
-    PN_CPP_EXTERN static const state REMOTE_MASK;     ///< Mask including all REMOTE_ bits (UNINIT, ACTIVE, CLOSED)
-    ///@}
+    PN_CPP_EXTERN static const state LOCAL_UNINIT;  ///< Local endpoint is uninitialized
+    PN_CPP_EXTERN static const state REMOTE_UNINIT; ///< Remote endpoint is uninitialized
+    PN_CPP_EXTERN static const state LOCAL_ACTIVE;  ///< Local endpoint is active
+    PN_CPP_EXTERN static const state REMOTE_ACTIVE; ///< Remote endpoint is active
+    PN_CPP_EXTERN static const state LOCAL_CLOSED;  ///< Local endpoint has been closed
+    PN_CPP_EXTERN static const state REMOTE_CLOSED; ///< Remote endpoint has been closed
+    PN_CPP_EXTERN static const state LOCAL_MASK;    ///< Mask including all LOCAL_ bits (UNINIT, ACTIVE, CLOSED)
+    PN_CPP_EXTERN static const state REMOTE_MASK;   ///< Mask including all REMOTE_ bits (UNINIT, ACTIVE, CLOSED)
 
 
+    /// Get the local error condition.
     virtual condition local_condition() const = 0;
+
+    /// Get the error condition of the remote endpoint.
     virtual condition remote_condition() const = 0;
 
     virtual ~endpoint() {}
 };
 
-///@cond INTERNAL
-
+/// @cond INTERNAL
+/// XXX important to expose?
+    
 template <class T> class iter_base  : public comparable<iter_base<T> > {
   public:
     typedef T value_type;
@@ -79,7 +79,6 @@ template <class T> class iter_base  : public comparable<iter_base<T> > {
     T ptr_;
     endpoint::state state_;
 };
-///@endcond INTERNAL
 
 /// An iterator range.
 template<class I> class range {
@@ -92,7 +91,9 @@ template<class I> class range {
   private:
     I begin_, end_;
 };
+    
+/// @endcond
 
 }
 
-#endif  /*!PROTON_CPP_H*/
+#endif // PROTON_CPP_H

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/error.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/error.hpp b/proton-c/bindings/cpp/include/proton/error.hpp
index 3083406..d4d5622 100644
--- a/proton-c/bindings/cpp/include/proton/error.hpp
+++ b/proton-c/bindings/cpp/include/proton/error.hpp
@@ -21,6 +21,7 @@
  * under the License.
  *
  */
+
 #include "proton/config.hpp"
 #include "proton/export.hpp"
 
@@ -29,26 +30,55 @@
 
 namespace proton {
 
-/** Functions in the proton namespace throw a subclass of proton::error on error. */
-struct error : public std::runtime_error { PN_CPP_EXTERN explicit error(const std::string&); };
+/// The base proton error.
+///    
+/// All exceptions thrown from functions in the proton namespace are
+/// subclasses of proton::error.
+struct error : public std::runtime_error {
+    /// @cond INTERNAL
+    /// XXX do we intend users to construct these (and subclasses)?
+    PN_CPP_EXTERN explicit error(const std::string&);
+    /// @endcond
+};
 
-/** Raised if timeout expires */
-struct timeout_error : public error { PN_CPP_EXTERN explicit timeout_error(const std::string&); };
+/// Raised if a timeout expires.
+struct timeout_error : public error {
+    /// @cond INTERNAL
+    PN_CPP_EXTERN explicit timeout_error(const std::string&);
+    /// @endcond
+};
 
-/** Raised if there is an error decoding AMQP data as a C++ value. */
-struct decode_error : public error { PN_CPP_EXTERN explicit decode_error(const std::string&); };
+/// @cond INTERNAL
+/// XXX change namespace
+    
+/// Raised if there is an error decoding AMQP data as a C++ value.
+struct decode_error : public error {
+    PN_CPP_EXTERN explicit decode_error(const std::string&);
+};
 
-/** Raised if there is an error encoding a C++ value as AMQP data. */
-struct encode_error : public error { PN_CPP_EXTERN explicit encode_error(const std::string&); };
+/// Raised if there is an error encoding a C++ value as AMQP data.
+struct encode_error : public error {
+    PN_CPP_EXTERN explicit encode_error(const std::string&);
+};
 
-/** Error reading or writing external IO. */
-struct io_error : public error { PN_CPP_EXTERN explicit io_error(const std::string&); };
+/// @endcond
 
-/** Attempt to use a closed resource (connnection, session or link). */
+/// @cond INTERNAL
+/// XXX need to discuss
+    
+/// Error reading or writing external IO.
+struct io_error : public error {
+    PN_CPP_EXTERN explicit io_error(const std::string&);
+};
+
+/// Attempt to use a closed resource (connnection, session, or link).
 struct closed_error : public io_error {
     PN_CPP_EXTERN explicit closed_error(const std::string& = default_msg);
     static const std::string default_msg;
 };
 
+/// @endcond
+
 }
-#endif  /*!PROTON_CPP_EXCEPTIONS_H*/
+
+#endif // PROTON_CPP_EXCEPTIONS_H

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/event.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/event.hpp b/proton-c/bindings/cpp/include/proton/event.hpp
index 641d553..844fcab 100644
--- a/proton-c/bindings/cpp/include/proton/event.hpp
+++ b/proton-c/bindings/cpp/include/proton/event.hpp
@@ -21,6 +21,7 @@
  * under the License.
  *
  */
+
 #include "proton/export.hpp"
 #include "proton/link.hpp"
 #include "proton/connection.hpp"
@@ -34,15 +35,20 @@ class handler;
 class container;
 class connection;
 
-/** Context information about a proton event */
+/// A context for a proton event.
+///
+/// @see proton::handler    
 class event {
   public:
     virtual PN_CPP_EXTERN ~event();
 
-    /// Return the name of the event type
+    /// Return the name of the event type.
     virtual PN_CPP_EXTERN std::string name() const = 0;
 
-    /// Get the container, throw an exception this event was not generated by a container.
+    /// Get the container.
+    ///
+    /// @throw proton::error if this event was not generated by a
+    /// container
     virtual PN_CPP_EXTERN class container& container() const;
 
     /// Get transport
@@ -51,15 +57,30 @@ class event {
     virtual PN_CPP_EXTERN class connection connection() const;
     /// Get session.
     virtual PN_CPP_EXTERN class session session() const;
-    /// Get sender @throws error if no sender.
+
+    /// Get sender.
+    ///
+    /// @throw proton::error if no sender
     virtual PN_CPP_EXTERN class sender sender() const;
-    /// Get receiver @throws error if no receiver.
+    
+    /// Get receiver.
+    ///
+    /// @throw proton::error if no receiver
     virtual PN_CPP_EXTERN class receiver receiver() const;
-    /// Get link @throws error if no link.
+
+    /// Get link.
+    ///
+    /// @throw proton::error if no link
     virtual PN_CPP_EXTERN class link link() const;
-    /// Get delivery @throws error if no delivery.
+    
+    /// Get delivery.
+    ///
+    /// @throw proton::error if no delivery
     virtual PN_CPP_EXTERN class delivery delivery() const;
-    /** Get message @throws error if no message. */
+
+    /// Get message.
+    ///
+    /// @throw proton::error if no message
     virtual PN_CPP_EXTERN class message &message() const;
 
   protected:
@@ -70,7 +91,6 @@ class event {
     event& operator=(const event&);
 };
 
-
 }
 
-#endif  /*!PROTON_CPP_EVENT_H*/
+#endif // PROTON_CPP_EVENT_H

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/export.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/export.hpp b/proton-c/bindings/cpp/include/proton/export.hpp
index fdebc6f..2eb330c 100644
--- a/proton-c/bindings/cpp/include/proton/export.hpp
+++ b/proton-c/bindings/cpp/include/proton/export.hpp
@@ -23,6 +23,7 @@
  */
 
 /// @cond INTERNAL
+
 /// import/export macros
 #if defined(WIN32) && !defined(PN_CPP_DECLARE_STATIC)
   //
@@ -44,6 +45,7 @@
 #else
 #  define PN_CPP_EXTERN PN_CPP_IMPORT
 #endif
-///@endcond
 
-#endif  /*!PN_CPP_IMPORTEXPORT_H*/
+/// @endcond
+
+#endif // PN_CPP_IMPORTEXPORT_H

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/handler.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/handler.hpp b/proton-c/bindings/cpp/include/proton/handler.hpp
index a681cff..44fad03 100644
--- a/proton-c/bindings/cpp/include/proton/handler.hpp
+++ b/proton-c/bindings/cpp/include/proton/handler.hpp
@@ -21,6 +21,7 @@
  * under the License.
  *
  */
+
 #include "proton/export.hpp"
 
 #include "proton/pn_unique_ptr.hpp"
@@ -31,69 +32,118 @@ class condition;
 class event;
 class messaging_adapter;
 
-/** messaging_handler base class. Provides a simpler set of events than
- * proton::proton_handler and automates some common tasks.  Subclass and
- * over-ride event handling member functions.
- * @see proton::messaging_event for meaning of events.
- */
+/// Callback functions for handling proton events.
+///
+/// Subclass and override event-handling member functions.
+///
+/// @see proton::event
 class handler
 {
   public:
-    /** Create a messaging_handler
-     *@param prefetch set flow control to automatically pre-fetch this many messages
-     *@param auto_accept automatically accept received messages after on_message()
-     *@param auto_settle automatically settle on receipt of delivery for sent messages.
-     *@param peer_close_is_error treat orderly remote connection close as error.
-     */
-    PN_CPP_EXTERN handler(int prefetch=10, bool auto_accept=true, bool auto_settle=true,
+    /// @cond INTERNAL
+    /// XXX move configuration to connection or container
+    
+    /// Create a handler.
+    ///
+    /// @param prefetch set flow control to automatically pre-fetch
+    /// this many messages
+    ///
+    /// @param auto_accept automatically accept received messages
+    /// after on_message()
+    ///
+    /// @param auto_settle automatically settle on receipt of delivery
+    /// for sent messages
+    ///
+    /// @param peer_close_is_error treat orderly remote connection
+    /// close as error
+    PN_CPP_EXTERN handler(int prefetch=10, bool auto_accept=true,
+                          bool auto_settle=true,
                           bool peer_close_is_error=false);
 
+    /// @endcond
+
     PN_CPP_EXTERN virtual ~handler();
 
-    ///@name Over-ride these member functions to handle events
-    ///@{
+    /// @name Event callbacks
+    ///
+    /// Override these member functions to handle events.
+    ///
+    /// @{
+
+    /// The event loop is starting.
     PN_CPP_EXTERN virtual void on_start(event &e);
+    /// A message is received.
     PN_CPP_EXTERN virtual void on_message(event &e);
+    /// A message can be sent.
     PN_CPP_EXTERN virtual void on_sendable(event &e);
 
+    /// The underlying network transport has closed.
     PN_CPP_EXTERN virtual void on_transport_close(event &e);
+    /// The underlying network transport has closed with an error
+    /// condition.
     PN_CPP_EXTERN virtual void on_transport_error(event &e);
 
+    /// The remote peer opened the connection.
     PN_CPP_EXTERN virtual void on_connection_open(event &e);
+    /// The remote peer closed the connection.
     PN_CPP_EXTERN virtual void on_connection_close(event &e);
+    /// The remote peer closed the connection with an error condition.
     PN_CPP_EXTERN virtual void on_connection_error(event &e);
 
+    /// The remote peer opened the session.
     PN_CPP_EXTERN virtual void on_session_open(event &e);
+    /// The remote peer closed the session.
     PN_CPP_EXTERN virtual void on_session_close(event &e);
+    /// The remote peer closed the session with an error condition.
     PN_CPP_EXTERN virtual void on_session_error(event &e);
 
+    /// The remote peer opened the link.
     PN_CPP_EXTERN virtual void on_link_open(event &e);
+    /// The remote peer closed the link.
     PN_CPP_EXTERN virtual void on_link_close(event &e);
+    /// The remote peer closed the link with an error condition.
     PN_CPP_EXTERN virtual void on_link_error(event &e);
 
+    /// The remote peer accepted an outgoing message.
     PN_CPP_EXTERN virtual void on_delivery_accept(event &e);
+    /// The remote peer rejected an outgoing message.
     PN_CPP_EXTERN virtual void on_delivery_reject(event &e);
+    /// The remote peer released an outgoing message.
     PN_CPP_EXTERN virtual void on_delivery_release(event &e);
+    /// The remote peer settled an outgoing message.
     PN_CPP_EXTERN virtual void on_delivery_settle(event &e);
 
+    /// The remote peer declared a transaction.
     PN_CPP_EXTERN virtual void on_transaction_declare(event &e);
+    /// The remote peer committed a transaction.
     PN_CPP_EXTERN virtual void on_transaction_commit(event &e);
+    /// The remote peer aborted a transaction.
     PN_CPP_EXTERN virtual void on_transaction_abort(event &e);
 
+    /// @cond INTERNAL
+    /// XXX settle API questions around task
+    /// A timer fired.
     PN_CPP_EXTERN virtual void on_timer(event &e);
+    /// @endcond
 
+    /// Fallback event handling.
     PN_CPP_EXTERN virtual void on_unhandled(event &e);
+    /// Fallback error handling.
     PN_CPP_EXTERN virtual void on_unhandled_error(event &e, const condition &c);
-    ///@}
+
+    /// @}
 
   private:
     pn_unique_ptr<messaging_adapter> messaging_adapter_;
+
+    /// @cond INTERNAL
     friend class container;
     friend class connection_engine;
     friend class connection_options;
     friend class link_options;
+    /// @endcond
 };
 
 }
 
-#endif  /*!PROTON_CPP_MESSAGING_HANDLER_H*/
+#endif // PROTON_CPP_MESSAGING_HANDLER_H

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/io.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/io.hpp b/proton-c/bindings/cpp/include/proton/io.hpp
index c4a3aa4..cf97f3b 100644
--- a/proton-c/bindings/cpp/include/proton/io.hpp
+++ b/proton-c/bindings/cpp/include/proton/io.hpp
@@ -1,6 +1,6 @@
-
 #ifndef SOCKET_IO_HPP
 #define SOCKET_IO_HPP
+
 /*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
@@ -24,42 +24,52 @@
 
 namespace proton {
 
-/** IO using sockets, file descriptors or handles.
- *
- * Note that you can use proton::connection_engine to communicate using AMQP
- * over your own IO implementation or to integrate an existing IO framework of
- * your choice.
- */
+/// IO using sockets, file descriptors, or handles.
+
+/// Note that you can use proton::connection_engine to communicate
+/// using AMQP over your own IO implementation or to integrate an
+/// existing IO framework of your choice.
+
 namespace io {
 
-///@name Setup and tear-down IO functionality.
-///
-/// Call proton::io::initialize before using any functions in the proton::io namespace.
-/// Call proton::io::finalize when you are done.
+/// @name Setup and teardown
 ///
-/// You can call initialize/finalize more than once as long as they are in
-/// matching pairs. Use proton::io::guard to call initialize/finalize around a scope.
+/// Call proton::io::initialize before using any functions in the
+/// proton::io namespace.  Call proton::io::finalize when you are
+/// done.
 ///
-/// Note on POSIX systems these are no-ops, but they are required for Windows.
+/// You can call initialize/finalize more than once as long as they
+/// are in matching pairs. Use proton::io::guard to call
+/// initialize/finalize around a scope.
 ///
-///@{
+/// Note that on POSIX systems these are no-ops, but they are required
+/// for Windows.
 ///
-/// Initialize the proton::io subsystem
+/// @{
+
+/// Initialize the proton::io subsystem.
 PN_CPP_EXTERN void initialize();
 
-/// Finalize the proton::io subsystem
-PN_CPP_EXTERN void finalize(); //nothrow
+/// Finalize the proton::io subsystem.
+PN_CPP_EXTERN void finalize(); // nothrow
+
+/// Use to call io::initialize and io::finalize around a scope.
 struct guard {
     guard() { initialize(); }
     ~guard() { finalize(); }
 };
-///@}
 
+/// @}
+
+/// An IO resource.
 typedef int64_t descriptor;
 
+/// @cond INTERNAL
+/// don't know what it is
 PN_CPP_EXTERN extern const descriptor INVALID_DESCRIPTOR;
+/// @endcond
 
-// Return the string describing the most recent IO error.
+/// Return a string describing the most recent IO error.
 PN_CPP_EXTERN std::string error_str();
 
 /// Open a TCP connection to the host:port (port can be a service name or number) from a proton::url.
@@ -90,6 +100,7 @@ class listener {
     descriptor socket_;
 };
 
+/// A connection_engine for socket-based IO.
 class socket_engine : public connection_engine {
   public:
     /// Wrap an open socket. Sets non-blocking mode.
@@ -101,6 +112,7 @@ class socket_engine : public connection_engine {
     /// Get the socket descriptor.
     descriptor socket() const { return socket_; }
 
+    /// Start the engine.
     PN_CPP_EXTERN void run();
 
   protected:

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/link.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/link.hpp b/proton-c/bindings/cpp/include/proton/link.hpp
index f3c62ef..1852c61 100644
--- a/proton-c/bindings/cpp/include/proton/link.hpp
+++ b/proton-c/bindings/cpp/include/proton/link.hpp
@@ -21,6 +21,7 @@
  * under the License.
  *
  */
+
 #include "proton/endpoint.hpp"
 #include "proton/export.hpp"
 #include "proton/message.hpp"
@@ -37,81 +38,104 @@ class sender;
 class receiver;
 class condition;
 
-/** Messages are transferred across a link. Base class for sender, receiver. */
-class link : public object<pn_link_t> , public endpoint
-{
+/// A named channel for sending or receiving messages.  It is the base
+/// class for sender and receiver.
+class link : public object<pn_link_t> , public endpoint {
   public:
+    /// @cond INTERNAL
     link(pn_link_t* l=0) : object<pn_link_t>(l) {}
+    /// @endcond
 
-    /* Endpoint behaviours */
+    // Endpoint behaviours
 
+    /// Get the state of this link.
     PN_CPP_EXTERN endpoint::state state() const;
+
     PN_CPP_EXTERN condition local_condition() const;
     PN_CPP_EXTERN condition remote_condition() const;
 
-    /** Locally open the link, not complete till messaging_handler::on_link_opened or
-     * proton_handler::link_remote_open
-     */
+    /// Locally open the link.  The operation is not complete till
+    /// handler::on_link_open.
     PN_CPP_EXTERN void open(const link_options &opts = link_options());
 
-    /** Locally close the link, not complete till messaging_handler::on_link_closed or
-     * proton_handler::link_remote_close
-     */
+    /// Locally close the link.  The operation is not complete till
+    /// handler::on_link_close.
     PN_CPP_EXTERN void close();
 
-    /** Return sender if this link is a sender, 0 if not. */
+    /// Return sender if this link is a sender, 0 if not.
     PN_CPP_EXTERN class sender sender();
+
+    /// Return sender if this link is a sender, 0 if not.
     PN_CPP_EXTERN const class sender sender() const;
 
-    /** Return receiver if this link is a receiver, 0 if not. */
+    /// Return receiver if this link is a receiver, 0 if not.
     PN_CPP_EXTERN class receiver receiver();
+
+    /// Return receiver if this link is a receiver, 0 if not.
     PN_CPP_EXTERN const class receiver receiver() const;
 
-    /** Credit available on the link */
+    /// Credit available on the link.
     PN_CPP_EXTERN int credit() const;
 
-    /** The number of queued deliveries for the link */
+    /// The number of deliveries queued on the link.
     PN_CPP_EXTERN int queued();
 
-    /** The number of unsettled deliveries on the link */
+    /// @cond INTERNAL
+    /// XXX ask about when this is used
+    /// The number of unsettled deliveries on the link.
     PN_CPP_EXTERN int unsettled();
+    /// @endcond
 
-    /** The count of credit returned.  */
+    /// @cond INTERNAL
+    /// XXX revisit mind-melting API inherited from C
     PN_CPP_EXTERN int drained();
+    /// @endcond
 
-    /** Local source of the link. */
+    /// Local source of the link.
     PN_CPP_EXTERN terminus local_source() const;
-    /** Local target of the link. */
+    
+    /// Local target of the link.
     PN_CPP_EXTERN terminus local_target() const;
-    /** Remote source of the link. */
+    
+    /// Remote source of the link.
     PN_CPP_EXTERN terminus remote_source() const;
-    /** Remote target of the link. */
+    
+    /// Remote target of the link.
     PN_CPP_EXTERN terminus remote_target() const;
 
-    /** Link name */
+    /// Get the link name.
     PN_CPP_EXTERN std::string name() const;
 
-    /** Connection that owns this link */
+    /// Connection that owns this link.
     PN_CPP_EXTERN class connection connection() const;
 
-    /** Session that owns this link */
+    /// Session that owns this link.
     PN_CPP_EXTERN class session session() const;
 
-    /** Set a custom handler for this link. */
+    /// @cond INTERNAL
+    /// XXX settle open questions
+    
+    /// Set a custom handler for this link.
     PN_CPP_EXTERN void handler(proton_handler &);
 
-    /** Unset any custom handler */
+    /// Unset any custom handler.
     PN_CPP_EXTERN void detach_handler();
 
-    /** Get message data from current delivery on link */
+    /// @cond INTERNAL
+
+    /// XXX ask about use case, revisit names
+    /// Get message data from current delivery on link.
     PN_CPP_EXTERN ssize_t recv(char* buffer, size_t size);
 
-    /** Advance the link one delivery */
+    /// XXX ask about use case, revisit names
+    /// Advance the link one delivery.
     PN_CPP_EXTERN bool advance();
 
-    /** Navigate the links in a connection - get next link with state */
+    /// XXX remove
+    /// Navigate the links in a connection - get next link with state.
     PN_CPP_EXTERN link next(endpoint::state) const;
 
+    /// XXX local versus remote, mutability
     PN_CPP_EXTERN link_options::sender_settle_mode sender_settle_mode();
     PN_CPP_EXTERN void sender_settle_mode(link_options::sender_settle_mode);
     PN_CPP_EXTERN link_options::receiver_settle_mode receiver_settle_mode();
@@ -119,8 +143,11 @@ class link : public object<pn_link_t> , public endpoint
     PN_CPP_EXTERN link_options::sender_settle_mode remote_sender_settle_mode();
     PN_CPP_EXTERN link_options::receiver_settle_mode remote_receiver_settle_mode();
 
+    /// @endcond
 };
 
+/// @cond INTERNAL
+/// XXX important to expose?
 /// An iterator for links.
 class link_iterator : public iter_base<link> {
   public:
@@ -134,12 +161,14 @@ class link_iterator : public iter_base<link> {
   private:
     const session* session_;
 };
+/// @endcond
 
 /// A range of links.
 typedef range<link_iterator> link_range;
+
 }
 
 #include "proton/sender.hpp"
 #include "proton/receiver.hpp"
 
-#endif  /*!PROTON_CPP_LINK_H*/
+#endif // PROTON_CPP_LINK_H

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/link_options.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/link_options.hpp b/proton-c/bindings/cpp/include/proton/link_options.hpp
index 085d512..932e8b3 100644
--- a/proton-c/bindings/cpp/include/proton/link_options.hpp
+++ b/proton-c/bindings/cpp/include/proton/link_options.hpp
@@ -21,6 +21,7 @@
  * under the License.
  *
  */
+
 #include "proton/config.hpp"
 #include "proton/export.hpp"
 #include "proton/pn_unique_ptr.hpp"
@@ -35,106 +36,146 @@ namespace proton {
 class proton_handler;
 class link;
 
-/** Options for creating a link.
- *
- * Options can be "chained" like this:
- *
- * l = container.create_sender(url, link_options().handler(h).browsing(true));
- *
- * You can also create an options object with common settings and use it as a base
- * for different connections that have mostly the same settings:
- *
- * link_options opts;
- * opts.browsing(true);
- * l1 = container.open_sender(url1, opts.handler(h1));
- * c2 = container.open_receiver(url2, opts.handler(h2));
- *
- * Normal value semantics, copy or assign creates a separate copy of the options.
- */
+/// Options for creating a link.
+///
+/// Options can be "chained" like this:
+///
+/// @code
+/// l = container.create_sender(url, link_options().handler(h).browsing(true));
+/// @endcode
+///
+/// You can also create an options object with common settings and use
+/// it as a base for different connections that have mostly the same
+/// settings:
+///
+/// @code
+/// link_options opts;
+/// opts.browsing(true);
+/// l1 = container.open_sender(url1, opts.handler(h1));
+/// c2 = container.open_receiver(url2, opts.handler(h2));
+/// @endcode
+///
+/// Normal value semantics: copy or assign creates a separate copy of
+/// the options.
 class link_options {
   public:
-    /** The message delivery policy to establish when opening a link. */
+    /// The message delivery policy to establish when opening a link.
     enum delivery_mode {
-        // No set policy.  The application must settle messages itself according to its own policy.
+        // No set policy.  The application must settle messages itself
+        // according to its own policy.
         DELIVERY_MODE_NONE = 0,
-        // Outgoing messages are settled immediately by the link.  There are no duplicates.
+        // Outgoing messages are settled immediately by the link.
+        // There are no duplicates.
         AT_MOST_ONCE,
-        // The receiver settles the delivery first with an accept/reject/release disposition.
-        // The sender waits to settle until after the disposition notification is received.
+        // The receiver settles the delivery first with an
+        // accept/reject/release disposition.  The sender waits to
+        // settle until after the disposition notification is
+        // received.
         AT_LEAST_ONCE
     };
 
-    /// Sender settlement behaviour for a link
+    /// Sender settlement behaviour for a link.
     enum sender_settle_mode {
         UNSETTLED = PN_SND_UNSETTLED,
         SETTLED = PN_SND_SETTLED,
         MIXED = PN_SND_MIXED
     };
 
-    /// Receiver settlement behaviour for a link
+    /// @cond INTERNAL
+    /// XXX discuss the names
+    /// Receiver settlement behaviour for a link.
     enum receiver_settle_mode {
         SETTLE_ALWAYS = PN_RCV_FIRST,
         SETTLE_SECOND= PN_RCV_SECOND
     };
+    /// @endcond
 
-    /** The lifetime of dynamically created nodes. */
+    /// The lifetime of dynamically created nodes.
     enum lifetime_policy {
         // The policy is unspecified.
         LIFETIME_UNSPECIFIED = 0,
-        // The lifetime of the dynamic node is scoped to lifetime of the creating link.
+        // The lifetime of the dynamic node is scoped to lifetime of
+        // the creating link.
         DELETE_ON_CLOSE = 0x2B,
-        // The node will be deleted when it is neither the source nor the target of any link.
+        // The node will be deleted when it is neither the source nor
+        // the target of any link.
         DELETE_ON_NO_LINKS = 0x2C,
-        // The node will be deleted when the creating link no longer exists and no messages remain at the node.
+        // The node will be deleted when the creating link no longer
+        // exists and no messages remain at the node.
         DELETE_ON_NO_MESSAGES = 0x2D,
-        // The node will be deleted when there are no links which have this node as
-        // their source or target, and there remain no messages at the node.
+        // The node will be deleted when there are no links which have
+        // this node as their source or target, and there remain no
+        // messages at the node.
         DELETE_ON_NO_LINKS_OR_MESSAGES = 0x2E
     };
 
-
+    /// Create an empty set of options.
     PN_CPP_EXTERN link_options();
+
+    /// Copy options.
     PN_CPP_EXTERN link_options(const link_options&);
+
     PN_CPP_EXTERN ~link_options();
+
+    /// Copy options.
     PN_CPP_EXTERN link_options& operator=(const link_options&);
 
     /// Override with options from other.
     PN_CPP_EXTERN void override(const link_options& other);
 
-    /** Set a handler for events scoped to the link.  If NULL, link-scoped events on the link are discarded. */
+    /// Set a handler for events scoped to the link.  If NULL,
+    /// link-scoped events on the link are discarded.
     PN_CPP_EXTERN link_options& handler(class handler *);
-    /** Receiver-only option to specify whether messages are browsed or
-        consumed.  Setting browsing to true is Equivalent to setting
-        distribution_mode(COPY).  Setting browsing to false is equivalent to
-        setting distribution_mode(MOVE). */
+
+    /// Receiver-only option to specify whether messages are browsed
+    /// or consumed.  Setting browsing to true is equivalent to
+    /// setting distribution_mode(COPY).  Setting browsing to false is
+    /// equivalent to setting distribution_mode(MOVE).
     PN_CPP_EXTERN link_options& browsing(bool);
-    /** Set the distribution mode for message transfer.  See terminus::distribution_mode. */
+
+    /// Set the distribution mode for message transfer.
     PN_CPP_EXTERN link_options& distribution_mode(enum terminus::distribution_mode);
-    /* Receiver-only option to create a durable subsription on the receiver.
-       Equivalent to setting the terminus durability to termins::DELIVERIES and
-       the expiry policy to terminus::EXPIRE_NEVER. */
+
+    /// Receiver-only option to create a durable subsription on the
+    /// receiver.  Equivalent to setting the terminus durability to
+    /// terminus::DELIVERIES and the expiry policy to
+    /// terminus::EXPIRE_NEVER.
     PN_CPP_EXTERN link_options& durable_subscription(bool);
-    /* Set the delivery mode on the link. */
+
+    /// Set the delivery mode on the link.
     PN_CPP_EXTERN link_options& delivery_mode(delivery_mode);
-    /* Request a dynamically generated node at the peer. */
+
+    /// Request a dynamically generated node at the peer.
     PN_CPP_EXTERN link_options& dynamic_address(bool);
-    /* Set the lifetime policy for a receiver to a dynamically created node. */
+
+    /// Set the lifetime policy for a receiver to a dynamically
+    /// created node.
     PN_CPP_EXTERN link_options& lifetime_policy(lifetime_policy);
-    /* Set the local address for the link. */
+
+    /// Set the local address for the link.
     PN_CPP_EXTERN link_options& local_address(const std::string &addr);
-    /* Set a selector on the receiver to str.  This sets a single registered filter on the link of
-       type apache.org:selector-filter with value str. */
+
+    /// @cond INTERNAL
+    /// XXX need to discuss spec issues, jms versus amqp filters
+    ///
+    /// Set a selector on the receiver to str.  This sets a single
+    /// registered filter on the link of type
+    /// apache.org:selector-filter with value str.
     PN_CPP_EXTERN link_options& selector(const std::string &str);
+    /// @endcond
 
   private:
-    friend class link;
     void apply(link&) const;
     proton_handler* handler() const;
 
     class impl;
     pn_unique_ptr<impl> impl_;
+
+    /// @cond INTERNAL
+    friend class link;
+    /// @endcond
 };
 
-} // namespace
+}
 
-#endif  /*!PROTON_CPP_LINK_OPTIONS_H*/
+#endif // PROTON_CPP_LINK_OPTIONS_H

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/message.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/message.hpp b/proton-c/bindings/cpp/include/proton/message.hpp
index aeabbcb..645da86 100644
--- a/proton-c/bindings/cpp/include/proton/message.hpp
+++ b/proton-c/bindings/cpp/include/proton/message.hpp
@@ -42,198 +42,222 @@ class delivery;
 class message_id;
 class annotation_key;
 
-/** An AMQP message. Value semantics, can be copied or assigned to make a new message. */
-class message
-{
+/// An AMQP message.
+///
+/// Value semantics: can be copied or assigned to make a new message.
+class message {
   public:
+    /// A map of string keys and AMQP scalar values.
     typedef std::map<std::string, scalar> property_map;
+
+    /// A map of AMQP annotation keys and AMQP values.
     typedef std::map<annotation_key, value> annotation_map;
 
+    /// Create an empty message.
     PN_CPP_EXTERN message();
+
+    /// Copy a message.
     PN_CPP_EXTERN message(const message&);
+
 #if PN_HAS_CPP11
     PN_CPP_EXTERN message(message&&);
 #endif
-    /// Construct a message from any value that can be assigned to a proton::value
-    template <class T> message(const T& x) : pn_msg_(0) { body() = x; }
 
+    /// Create a message with its body set from any value that can be
+    /// assigned to a proton::value.
+    template <class T> message(const T& x) : pn_msg_(0) { body() = x; }
 
     PN_CPP_EXTERN ~message();
 
+    /// Copy a message.
     PN_CPP_EXTERN message& operator=(const message&);
 
-    /** Clear the message content and properties. */
-    PN_CPP_EXTERN void clear();
+    /// @name Basic properties and methods
+    /// @{
 
-    ///@name Standard AMQP message properties
-    ///@{
+    /// Clear the message content and properties.
+    PN_CPP_EXTERN void clear();
 
     PN_CPP_EXTERN void id(const message_id& id);
     PN_CPP_EXTERN message_id id() const;
 
+    /// @cond INTERNAL
+    /// XXX consider just user, in order to be consistent with similar
+    /// fields elsewhere in the API
     PN_CPP_EXTERN void user_id(const std::string &user);
     PN_CPP_EXTERN std::string user_id() const;
+    /// @endcond
 
-    PN_CPP_EXTERN void address(const std::string &addr);
-    PN_CPP_EXTERN std::string address() const;
-
-    PN_CPP_EXTERN void subject(const std::string &s);
-    PN_CPP_EXTERN std::string subject() const;
+    /// Encode entire message into a byte vector, growing it if
+    /// necessary.
+    PN_CPP_EXTERN void encode(std::vector<char> &bytes) const;
 
-    PN_CPP_EXTERN void reply_to(const std::string &s);
-    PN_CPP_EXTERN std::string reply_to() const;
+    /// Return encoded message as a byte vector.
+    PN_CPP_EXTERN std::vector<char> encode() const;
 
-    PN_CPP_EXTERN void correlation_id(const message_id&);
-    PN_CPP_EXTERN message_id correlation_id() const;
+    /// Decode from string data into the message.
+    PN_CPP_EXTERN void decode(const std::vector<char> &bytes);
 
-    PN_CPP_EXTERN void content_type(const std::string &s);
-    PN_CPP_EXTERN std::string content_type() const;
+    /// @cond INTERNAL
+    /// XXX should a delivery know its own link already?
+    ///
+    /// Decode the message corresponding to a delivery from a link.
+    PN_CPP_EXTERN void decode(proton::link, proton::delivery);
+    /// @endcond
 
-    PN_CPP_EXTERN void content_encoding(const std::string &s);
-    PN_CPP_EXTERN std::string content_encoding() const;
+    /// @}
 
-    PN_CPP_EXTERN void expiry_time(amqp_timestamp t);
-    PN_CPP_EXTERN amqp_timestamp expiry_time() const;
+    /// @name Routing
+    /// @{
 
-    PN_CPP_EXTERN void creation_time(amqp_timestamp t);
-    PN_CPP_EXTERN amqp_timestamp creation_time() const;
+    PN_CPP_EXTERN void address(const std::string &addr);
+    PN_CPP_EXTERN std::string address() const;
+    
+    PN_CPP_EXTERN void reply_to(const std::string &addr);
+    PN_CPP_EXTERN std::string reply_to() const;
 
-    PN_CPP_EXTERN void group_id(const std::string &s);
-    PN_CPP_EXTERN std::string group_id() const;
+    PN_CPP_EXTERN void correlation_id(const message_id&);
+    PN_CPP_EXTERN message_id correlation_id() const;
 
-    PN_CPP_EXTERN void reply_to_group_id(const std::string &s);
-    PN_CPP_EXTERN std::string reply_to_group_id() const;
+    /// @}
 
-    ///@}
+    /// @name Content
+    /// @{
 
-    /** Set the body, equivalent to body() = v */
+    /// Set the body, equivalent to body() = v
     template<class T> void body(const T& v) { body() = v; }
 
-    /** Get the body. */
+    /// Get the body.
     PN_CPP_EXTERN const value& body() const;
 
-    /** Get a reference to the body that can be modified in-place. */
+    /// Get a reference to the body that can be modified in-place.
     PN_CPP_EXTERN value& body();
 
-    /** Application properties map, can be modified in place. */
-    PN_CPP_EXTERN property_map& application_properties();
-    PN_CPP_EXTERN const property_map& application_properties() const;
-
-    /** Message annotations map, can be modified in place. */
-    PN_CPP_EXTERN annotation_map& message_annotations();
-    PN_CPP_EXTERN const annotation_map& message_annotations() const;
-
-    /** Delivery annotations map, can be modified in place. */
-    PN_CPP_EXTERN annotation_map& delivery_annotations();
-    PN_CPP_EXTERN const annotation_map& delivery_annotations() const;
+    PN_CPP_EXTERN void subject(const std::string &s);
+    PN_CPP_EXTERN std::string subject() const;
 
-    /** Encode entire message into a byte vector, growing it if necessary. */
-    PN_CPP_EXTERN void encode(std::vector<char> &bytes) const;
+    PN_CPP_EXTERN void content_type(const std::string &s);
+    PN_CPP_EXTERN std::string content_type() const;
 
-    /** Return encoded message as a byte vector */
-    PN_CPP_EXTERN std::vector<char> encode() const;
+    PN_CPP_EXTERN void content_encoding(const std::string &s);
+    PN_CPP_EXTERN std::string content_encoding() const;
 
-    /** Decode from string data into the message. */
-    PN_CPP_EXTERN void decode(const std::vector<char> &bytes);
+    PN_CPP_EXTERN void expiry_time(amqp_timestamp t);
+    PN_CPP_EXTERN amqp_timestamp expiry_time() const;
 
-    /** Decode the message corresponding to a delivery from a link. */
-    PN_CPP_EXTERN void decode(proton::link, proton::delivery);
+    PN_CPP_EXTERN void creation_time(amqp_timestamp t);
+    PN_CPP_EXTERN amqp_timestamp creation_time() const;
 
-    /**
-     * Get the inferred flag for a message.
-     *
-     * The inferred flag for a message indicates how the message content
-     * is encoded into AMQP sections. If inferred is true then binary and
-     * list values in the body of the message will be encoded as AMQP DATA
-     * and AMQP SEQUENCE sections, respectively. If inferred is false,
-     * then all values in the body of the message will be encoded as AMQP
-     * VALUE sections regardless of their type.
-     */
+    /// Get the inferred flag for a message.
+    ///
+    /// The inferred flag for a message indicates how the message
+    /// content is encoded into AMQP sections. If inferred is true
+    /// then binary and list values in the body of the message will be
+    /// encoded as AMQP DATA and AMQP SEQUENCE sections,
+    /// respectively. If inferred is false, then all values in the
+    /// body of the message will be encoded as AMQP VALUE sections
+    /// regardless of their type.
     PN_CPP_EXTERN bool inferred() const;
-    /** Get the inferred flag for a message. */
+    /// Set the inferred flag for a message.
     PN_CPP_EXTERN void inferred(bool);
 
-    /**
-     * Get the durable flag for a message.
-     *
-     * The durable flag indicates that any parties taking responsibility
-     * for the message must durably store the content.
-     *
-     * @return the value of the durable flag
-     */
+    /// @}
+
+    /// @name Transfer headers
+    /// @{
+    
+    /// Get the durable flag for a message.
+    ///
+    /// The durable flag indicates that any parties taking
+    /// responsibility for the message must durably store the content.
+    ///
+    /// @return the value of the durable flag
     PN_CPP_EXTERN bool durable() const;
-    /** Set the durable flag for a message. */
+    /// Set the durable flag for a message.
     PN_CPP_EXTERN void durable(bool);
 
-    /**
-     * Get the ttl for a message.
-     *
-     * The ttl for a message determines how long a message is considered
-     * live. When a message is held for retransmit, the ttl is
-     * decremented. Once the ttl reaches zero, the message is considered
-     * dead. Once a message is considered dead it may be dropped.
-     *
-     * @return the ttl in milliseconds
-     */
+    /// Get the TTL for a message.
+    ///
+    /// The TTL (time to live) for a message determines how long a
+    /// message is considered live. When a message is held for
+    /// retransmit, the TTL is decremented. Once the TTL reaches zero,
+    /// the message is considered dead. Once a message is considered
+    /// dead it may be dropped.
     PN_CPP_EXTERN duration ttl() const;
-    /** Set the ttl for a message */
+
+    /// Set the TTL for a message.
     PN_CPP_EXTERN void ttl(duration);
 
-    /**
-     * Get the priority for a message.
-     *
-     * The priority of a message impacts ordering guarantees. Within a
-     * given ordered context, higher priority messages may jump ahead of
-     * lower priority messages.
-     *
-     * @return the message priority
-     */
+    /// Get the priority for a message.
+    ///
+    /// The priority of a message impacts ordering guarantees. Within
+    /// a given ordered context, higher priority messages may jump
+    /// ahead of lower priority messages.
     PN_CPP_EXTERN uint8_t priority() const;
-    /** Set the priority for a message. */
+
+    /// Set the priority for a message.
     PN_CPP_EXTERN void priority(uint8_t);
 
-    /**
-     * Get the first acquirer flag for a message.
-     *
-     * When set to true, the first acquirer flag for a message indicates
-     * that the recipient of the message is the first recipient to acquire
-     * the message, i.e. there have been no failed delivery attempts to
-     * other acquirers. Note that this does not mean the message has not
-     * been delivered to, but not acquired, by other recipients.
-     *
-     * @return the first acquirer flag for the message
-     */
+    /// Get the first acquirer flag for a message.
+    ///
+    /// When set to true, the first acquirer flag for a message
+    /// indicates that the recipient of the message is the first
+    /// recipient to acquire the message, i.e. there have been no
+    /// failed delivery attempts to other acquirers.  Note that this
+    /// does not mean the message has not been delivered to, but not
+    /// acquired, by other recipients.
     PN_CPP_EXTERN bool first_acquirer() const;
-    /** Set the first acquirer flag for a message. */
+    
+    /// Set the first acquirer flag for a message.
     PN_CPP_EXTERN void first_acquirer(bool);
 
-    /**
-     * Get the delivery count for a message.
-     *
-     * The delivery count field tracks how many attempts have been made to
-     * delivery a message.
-     *
-     * @return the delivery count for the message
-     */
+    /// Get the delivery count for a message.
+    ///
+    /// The delivery count field tracks how many attempts have been made to
+    /// delivery a message.
     PN_CPP_EXTERN uint32_t delivery_count() const;
-    /** Get the delivery count for a message. */
+
+    /// Get the delivery count for a message.
     PN_CPP_EXTERN void delivery_count(uint32_t);
 
-    /**
-     * Get the group sequence for a message.
-     *
-     * The group sequence of a message identifies the relative ordering of
-     * messages within a group. The default value for the group sequence
-     * of a message is zero.
-     *
-     * @return the group sequence for the message
-     */
+    /// @}
+
+    /// @name Message groups
+    /// @{
+
+    PN_CPP_EXTERN void group_id(const std::string &s);
+    PN_CPP_EXTERN std::string group_id() const;
+
+    PN_CPP_EXTERN void reply_to_group_id(const std::string &s);
+    PN_CPP_EXTERN std::string reply_to_group_id() const;
+
+    /// Get the group sequence for a message.
+    ///
+    /// The group sequence of a message identifies the relative
+    /// ordering of messages within a group. The default value for the
+    /// group sequence of a message is zero.
     PN_CPP_EXTERN int32_t group_sequence() const;
-    /** Set the group sequence for a message. */
+    /// Set the group sequence for a message.
     PN_CPP_EXTERN void group_sequence(int32_t);
 
+    /// @}
+    
+    /// @name Extended attributes
+    /// @{
 
-  friend PN_CPP_EXTERN void swap(message&, message&);
+    /// Application properties map, can be modified in place.
+    PN_CPP_EXTERN property_map& application_properties();
+    PN_CPP_EXTERN const property_map& application_properties() const;
+
+    /// Message annotations map, can be modified in place.
+    PN_CPP_EXTERN annotation_map& message_annotations();
+    PN_CPP_EXTERN const annotation_map& message_annotations() const;
+
+    /// Delivery annotations map, can be modified in place.
+    PN_CPP_EXTERN annotation_map& delivery_annotations();
+    PN_CPP_EXTERN const annotation_map& delivery_annotations() const;
+
+    /// @}
 
   private:
     pn_message_t *pn_msg() const;
@@ -243,8 +267,13 @@ class message
     mutable property_map application_properties_;
     mutable annotation_map message_annotations_;
     mutable annotation_map delivery_annotations_;
+
+    /// @cond INTERNAL
+    /// XXX settle necessity (there were some other options)
+    friend PN_CPP_EXTERN void swap(message&, message&);
+    /// @endcond
 };
 
 }
 
-#endif  /*!PROTON_CPP_MESSAGE_H*/
+#endif // PROTON_CPP_MESSAGE_H

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/message_id.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/message_id.hpp b/proton-c/bindings/cpp/include/proton/message_id.hpp
index b08482f..0adef07 100644
--- a/proton-c/bindings/cpp/include/proton/message_id.hpp
+++ b/proton-c/bindings/cpp/include/proton/message_id.hpp
@@ -1,5 +1,6 @@
 #ifndef MESSAGE_ID_HPP
 #define MESSAGE_ID_HPP
+
 /*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
@@ -23,18 +24,28 @@
 #include "proton/scalar.hpp"
 
 namespace proton {
+    
 class encoder;
 class decoder;
 
-/** A message_id can contain one of the following types:
- * uint64_t, amqp_uuid, amqp_binary or amqp_string.
- */
+/// An AMQP message ID.
+///    
+/// It can contain one of the following types:
+///
+///  - uint64_t
+///  - proton::amqp::amqp_uuid
+///  - proton::amqp::amqp_binary
+///  - proton::amqp::amqp_string
 class message_id : public restricted_scalar {
   public:
+    /// Create an empty (0) message ID.
     message_id() { scalar_ = uint64_t(0); }
 
-    ///@name Assign a C++ value, deduce the AMQP type()
-    ///@{
+    /// @name Assignment operators
+    ///
+    /// Assign a C++ value, deduce the AMQP type()
+    ///
+    /// @{
     message_id& operator=(uint64_t x) { scalar_ = x; return *this; }
     message_id& operator=(const amqp_uuid& x) { scalar_ = x; return *this; }
     message_id& operator=(const amqp_binary& x) { scalar_ = x; return *this; }
@@ -43,21 +54,31 @@ class message_id : public restricted_scalar {
     message_id& operator=(const std::string& x) { scalar_ = amqp_string(x); return *this; }
     /// char* is encoded as amqp_string
     message_id& operator=(const char *x) { scalar_ = amqp_string(x); return *this; }
-    ///@}
+    /// @}
 
-    /// Converting constructor from any type that we can assign from.
+    /// Create a message ID from any type that we can assign from.
     template <class T> message_id(T x) { *this = x; }
 
+    /// @name Get methods
+    ///
+    /// get(T&) extracts the value if the types match exactly and
+    /// throws type_error otherwise.
+    ///
+    /// @{
     void get(uint64_t& x) const { scalar_.get(x); }
     void get(amqp_uuid& x) const { scalar_.get(x); }
     void get(amqp_binary& x) const { scalar_.get(x); }
     void get(amqp_string& x) const { scalar_.get(x); }
+    /// @}
 
+    /// Return the value as type T.
     template<class T> T get() const { T x; get(x); return x; }
 
-  friend PN_CPP_EXTERN encoder operator<<(encoder, const message_id&);
-  friend PN_CPP_EXTERN decoder operator>>(decoder, message_id&);
-  friend class message;
+    /// @cond INTERNAL
+    friend PN_CPP_EXTERN encoder operator<<(encoder, const message_id&);
+    friend PN_CPP_EXTERN decoder operator>>(decoder, message_id&);
+    friend class message;
+    /// @endcond
 };
 
 }

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/object.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/object.hpp b/proton-c/bindings/cpp/include/proton/object.hpp
index cc2bd31..4e12e6f 100644
--- a/proton-c/bindings/cpp/include/proton/object.hpp
+++ b/proton-c/bindings/cpp/include/proton/object.hpp
@@ -1,5 +1,6 @@
 #ifndef OBJECT_HPP
 #define OBJECT_HPP
+
 /*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
@@ -19,6 +20,8 @@
  * under the License.
  */
 
+/// @cond INTERNAL
+
 #include "proton/config.hpp"
 #include "proton/export.hpp"
 #include "proton/comparable.hpp"
@@ -26,7 +29,6 @@
 
 namespace proton {
 
-///@cond INTERNAL
 class pn_ptr_base {
   protected:
     PN_CPP_EXTERN static void incref(void* p);
@@ -51,9 +53,6 @@ template <class T> class pn_ptr : private pn_ptr_base, public comparable<pn_ptr<
     T* release() { T *p = ptr_; ptr_ = 0; return p; }
     bool operator!() const { return !ptr_; }
 
-  friend bool operator==(const pn_ptr& a, const pn_ptr& b) { return a.ptr_ == b.ptr_; }
-  friend bool operator<(const pn_ptr& a, const pn_ptr& b) { return a.ptr_ < b.ptr_; }
-
     static pn_ptr take_ownership(T* p) { return pn_ptr<T>(p, true); }
 
   private:
@@ -62,29 +61,31 @@ template <class T> class pn_ptr : private pn_ptr_base, public comparable<pn_ptr<
     // Note that it is the presence of the bool in the constructor signature that matters
     // to get the "transfer ownership" constructor: The value of the bool isn't checked.
     pn_ptr(T* p, bool) : ptr_(p) {}
+
+    friend bool operator==(const pn_ptr& a, const pn_ptr& b) { return a.ptr_ == b.ptr_; }
+    friend bool operator<(const pn_ptr& a, const pn_ptr& b) { return a.ptr_ < b.ptr_; }
 };
 
 template <class T> pn_ptr<T> take_ownership(T* p) { return pn_ptr<T>::take_ownership(p); }
 
-///@endcond INTERNAL
-
-/**
- * Base class for proton object types
- */
+/// Base class for proton object types.
 template <class T> class object : public comparable<object<T> > {
   public:
     bool operator!() const { return !object_; }
 
-  friend bool operator==(const object& a, const object& b) { return a.object_ == b.object_; }
-  friend bool operator<(const object& a, const object& b) { return a.object_ < b.object_; }
-
   protected:
     object(pn_ptr<T> o) : object_(o) {}
     T* pn_object() const { return object_.get(); }
 
   private:
     pn_ptr<T> object_;
+
+    friend bool operator==(const object& a, const object& b) { return a.object_ == b.object_; }
+    friend bool operator<(const object& a, const object& b) { return a.object_ < b.object_; }
 };
 
 }
+
+/// @endcond
+
 #endif // OBJECT_HPP

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/pn_unique_ptr.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/pn_unique_ptr.hpp b/proton-c/bindings/cpp/include/proton/pn_unique_ptr.hpp
index 6533b0b..12636eb 100644
--- a/proton-c/bindings/cpp/include/proton/pn_unique_ptr.hpp
+++ b/proton-c/bindings/cpp/include/proton/pn_unique_ptr.hpp
@@ -19,21 +19,22 @@
  * under the License.
  */
 
+/// @cond INTERNAL
+/// XXX discuss where this gets exposed
+    
 #include "proton/config.hpp"
 #include <memory>
 
 namespace proton {
 
-/**
- * A simple unique ownership pointer, used as a return value from functions that
- * transfer ownership to the caller.
- *
- * pn_unique_ptr return values should be converted immediately to
- * std::unique_ptr if that is available or std::auto_ptr (by calling release())
- * for older C++. You should not use pn_unique_ptr in your own code, it is a
- * limited pointer class designed only to work around differences between C++11
- * and C++03.
- */
+/// A simple unique ownership pointer, used as a return value from
+/// functions that transfer ownership to the caller.
+///
+/// pn_unique_ptr return values should be converted immediately to
+/// std::unique_ptr if that is available or std::auto_ptr (by calling
+/// release()) for older C++. You should not use pn_unique_ptr in your
+/// own code.  It is a limited pointer class designed only to work
+/// around differences between C++11 and C++03.
 template <class T> class pn_unique_ptr {
   public:
     pn_unique_ptr(T* p=0) : ptr_(p) {}
@@ -59,5 +60,8 @@ template <class T> class pn_unique_ptr {
     T* ptr_;
 };
 
+/// @endcond
+
 }
+
 #endif // UNIQUE_PTR_HPP

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/reactor.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/reactor.hpp b/proton-c/bindings/cpp/include/proton/reactor.hpp
index 7592a14..8251405 100644
--- a/proton-c/bindings/cpp/include/proton/reactor.hpp
+++ b/proton-c/bindings/cpp/include/proton/reactor.hpp
@@ -1,5 +1,6 @@
 #ifndef REACTOR_HPP
 #define REACTOR_HPP
+
 /*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
@@ -19,6 +20,9 @@
  * under the License.
  */
 
+/// @cond INTERNAL
+/// XXX remove
+
 #include "proton/object.hpp"
 #include "proton/duration.hpp"
 
@@ -91,4 +95,7 @@ class reactor : public object<pn_reactor_t> {
 };
 
 }
+
+/// @endcond
+
 #endif // REACTOR_HPP

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/receiver.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/receiver.hpp b/proton-c/bindings/cpp/include/proton/receiver.hpp
index d0df703..11569e4 100644
--- a/proton-c/bindings/cpp/include/proton/receiver.hpp
+++ b/proton-c/bindings/cpp/include/proton/receiver.hpp
@@ -21,6 +21,7 @@
  * under the License.
  *
  */
+
 #include "proton/export.hpp"
 #include "proton/endpoint.hpp"
 #include "proton/link.hpp"
@@ -31,11 +32,12 @@ struct pn_connection_t;
 
 namespace proton {
 
-/// A receiving link
-class receiver : public link
-{
+/// A link for receiving messages.
+class receiver : public link {
   public:
+    /// @cond INTERNAL
     receiver(pn_link_t* r=0) : link(r) {}
+    /// @endcond
 
     /// Add credit to the link
     PN_CPP_EXTERN void flow(int count);
@@ -43,4 +45,4 @@ class receiver : public link
 
 }
 
-#endif  /*!PROTON_CPP_RECEIVER_H*/
+#endif // PROTON_CPP_RECEIVER_H

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/reconnect_timer.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/reconnect_timer.hpp b/proton-c/bindings/cpp/include/proton/reconnect_timer.hpp
index f89f47e..d7b720f 100644
--- a/proton-c/bindings/cpp/include/proton/reconnect_timer.hpp
+++ b/proton-c/bindings/cpp/include/proton/reconnect_timer.hpp
@@ -22,6 +22,9 @@
  *
  */
 
+/// @cond INTERNAL
+/// XXX more discussion
+
 #include "proton/export.hpp"
 #include "proton/types.hpp"
 #include "proton/reactor.hpp"
@@ -55,9 +58,12 @@ class reconnect_timer
     int32_t next_delay_;
     pn_timestamp_t timeout_deadline_;
     reactor reactor_;
+
     friend class connector;
 };
 
+/// @endcond
+    
 }
 
-#endif  /*!PROTON_CPP_RECONNECT_H*/
+#endif // PROTON_CPP_RECONNECT_H

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/sasl.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/sasl.hpp b/proton-c/bindings/cpp/include/proton/sasl.hpp
index 98cfea7..53052d7 100644
--- a/proton-c/bindings/cpp/include/proton/sasl.hpp
+++ b/proton-c/bindings/cpp/include/proton/sasl.hpp
@@ -21,40 +21,59 @@
  * under the License.
  *
  */
+
 #include "proton/export.hpp"
 #include "proton/sasl.h"
 #include <string>
 
 namespace proton {
 
+/// SASL information.
 class sasl {
   public:
-    /** The result of the SASL negotiation */
+    /// The result of the SASL negotiation.
     enum outcome {
-        NONE = PN_SASL_NONE,   /** negotiation not completed */
-        OK = PN_SASL_OK,       /** authentication succeeded */
-        AUTH = PN_SASL_AUTH,   /** failed due to bad credentials */
-        SYS = PN_SASL_SYS,     /** failed due to a system error */
-        PERM = PN_SASL_PERM,   /** failed due to unrecoverable error */
-        TEMP = PN_SASL_TEMP    /** failed due to transient error */
+        NONE = PN_SASL_NONE,   ///< Negotiation not completed
+        OK = PN_SASL_OK,       ///< Authentication succeeded
+        AUTH = PN_SASL_AUTH,   ///< Failed due to bad credentials
+        SYS = PN_SASL_SYS,     ///< Failed due to a system error
+        PERM = PN_SASL_PERM,   ///< Failed due to unrecoverable error
+        TEMP = PN_SASL_TEMP    ///< Failed due to transient error
     };
 
+    /// @cond INTERNAL
+    /// XXX need to discuss
     sasl(pn_sasl_t* s) : object_(s) {}
     PN_CPP_EXTERN static bool extended();
     PN_CPP_EXTERN void done(enum outcome);
+    /// @endcond
+
+    /// Get the outcome.
     PN_CPP_EXTERN enum outcome outcome() const;
+
+    /// Get the user name.
     PN_CPP_EXTERN std::string user() const;
+
+    /// Get the mechanism.
     PN_CPP_EXTERN std::string mech() const;
 
+    /// @cond INTERNAL
     PN_CPP_EXTERN void allow_insecure_mechs(bool);
+    /// @endcond
+
+    /// True if insecure mechanisms are permitted.
     PN_CPP_EXTERN bool allow_insecure_mechs();
+
+    /// @cond INTERNAL
+    /// XXX setters? versus connection options
     PN_CPP_EXTERN void allowed_mechs(const std::string &);
     PN_CPP_EXTERN void config_name(const std::string&);
     PN_CPP_EXTERN void config_path(const std::string&);
+    /// @endcond
 private:
     pn_sasl_t* object_;
 };
 
 }
 
-#endif  /*!PROTON_CPP_SASL_H*/
+#endif // PROTON_CPP_SASL_H

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/scalar.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/scalar.hpp b/proton-c/bindings/cpp/include/proton/scalar.hpp
index c06a675..3975301 100644
--- a/proton-c/bindings/cpp/include/proton/scalar.hpp
+++ b/proton-c/bindings/cpp/include/proton/scalar.hpp
@@ -1,5 +1,6 @@
 #ifndef SCALAR_HPP
 #define SCALAR_HPP
+
 /*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
@@ -30,11 +31,16 @@ namespace proton {
 class encoder;
 class decoder;
 
-/** scalar holds an instance of any scalar AMQP type. */
+/// A holder for an instance of any scalar AMQP type.
 class scalar : public comparable<scalar> {
   public:
+    /// Create an empty scalar.
     PN_CPP_EXTERN scalar();
+
+    /// Copy a scalar.
     PN_CPP_EXTERN scalar(const scalar&);
+
+    /// Copy a scalar.
     PN_CPP_EXTERN scalar& operator=(const scalar&);
 
     /// Type for the value in the scalar, NULL_TYPE if empty()
@@ -43,8 +49,11 @@ class scalar : public comparable<scalar> {
     /// True if the scalar is empty.
     PN_CPP_EXTERN bool empty() const;
 
-    ///@name Assign a C++ value, deduce the AMQP type()
-    ///@{
+    /// @name Assignment operators
+    ///
+    /// Assign a C++ value and deduce the AMQP type().
+    ///
+    /// @{
     PN_CPP_EXTERN scalar& operator=(bool);
     PN_CPP_EXTERN scalar& operator=(uint8_t);
     PN_CPP_EXTERN scalar& operator=(int8_t);
@@ -67,13 +76,17 @@ class scalar : public comparable<scalar> {
     PN_CPP_EXTERN scalar& operator=(const amqp_binary&);
     PN_CPP_EXTERN scalar& operator=(const std::string& s); ///< Treated as an AMQP string
     PN_CPP_EXTERN scalar& operator=(const char* s);        ///< Treated as an AMQP string
-    ///@}
+    /// @}
 
-    /// Construct from any type that we can assign from.
+    /// Create a scalar from any type that we can assign from.
     template <class T> explicit scalar(T x) { *this = x; }
 
-    ///@name get(T&) extracts the value if the types match exactly, throws type_error otherwise.
-    ///@{
+    /// @name Get methods
+    ///
+    /// get(T&) extracts the value if the types match exactly and
+    /// throws type_error otherwise.
+    ///
+    /// @{
     PN_CPP_EXTERN void get(bool&) const;
     PN_CPP_EXTERN void get(uint8_t&) const;
     PN_CPP_EXTERN void get(int8_t&) const;
@@ -95,25 +108,30 @@ class scalar : public comparable<scalar> {
     PN_CPP_EXTERN void get(amqp_symbol&) const;
     PN_CPP_EXTERN void get(amqp_binary&) const;
     PN_CPP_EXTERN void get(std::string&) const; ///< Treated as an AMQP string
-    ///@}
+    /// @}
 
-    ///@ get<T>() is like get(T&) but returns the value..
+    /// get<T>() is like get(T&) but returns the value.
     template<class T> T get() const { T x; get(x); return x; }
 
-    ///@name as_ methods do "loose" conversion, they will convert the scalar's
-    ///value to the requested type if possible, else throw type_error
-    ///@{
-    PN_CPP_EXTERN int64_t as_int() const;     ///< Allowed if type_id_is_integral(type())
-    PN_CPP_EXTERN uint64_t as_uint() const;   ///< Allowed if type_id_is_integral(type())
-    PN_CPP_EXTERN double as_double() const;    ///< Allowed if type_id_is_floating_point(type())
+    /// @name As methods
+    ///
+    /// As methods do "loose" conversion.  They will convert the
+    /// scalar's value to the requested type if possible, else throw
+    /// type_error.
+    ///
+    /// @{
+    PN_CPP_EXTERN int64_t as_int() const;        ///< Allowed if type_id_is_integral(type())
+    PN_CPP_EXTERN uint64_t as_uint() const;      ///< Allowed if type_id_is_integral(type())
+    PN_CPP_EXTERN double as_double() const;      ///< Allowed if type_id_is_floating_point(type())
     PN_CPP_EXTERN std::string as_string() const; ///< Allowed if type_id_is_string_like(type())
-    ///@}
+    /// @}
 
+    /// @cond INTERNAL
+    
   friend PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, const scalar&);
   friend PN_CPP_EXTERN encoder operator<<(encoder, const scalar&);
   friend PN_CPP_EXTERN decoder operator>>(decoder, scalar&);
 
-
     /// Scalars with different type() are considered unequal even if the values
     /// are equal as numbers or strings.
   friend PN_CPP_EXTERN bool operator==(const scalar& x, const scalar& y);
@@ -121,6 +139,8 @@ class scalar : public comparable<scalar> {
     /// For scalars of different type(), operator< sorts by order of type().
   friend PN_CPP_EXTERN bool operator<(const scalar& x, const scalar& y);
 
+    /// @endcond
+    
   private:
     void ok(pn_type_t) const;
     void set(const std::string&, pn_type_t);
@@ -131,29 +151,39 @@ class scalar : public comparable<scalar> {
   friend class message;
 };
 
-///@internal base for restricted scalar types
+/// @cond INTERNAL
+/// XXX should it be public?
+    
+/// Base class for restricted scalar types.
 class restricted_scalar : public comparable<restricted_scalar> {
   public:
     operator const scalar&() const { return scalar_; }
     type_id type() const { return scalar_.type(); }
 
-    ///@name as_ methods do "loose" conversion, they will convert the scalar's
-    ///value to the requested type if possible, else throw type_error
-    ///@{
+    /// @name As methods
+    ///
+    /// As methods do "loose" conversion.  They will convert the
+    /// scalar's value to the requested type if possible, else throw
+    /// type_error.
+    ///
+    /// @{
     int64_t as_int() const { return scalar_.as_int(); }
     uint64_t as_uint() const { return scalar_.as_uint(); }
     double as_double() const { return scalar_.as_double();  }
     std::string as_string() const { return scalar_.as_string(); }
-    ///@}
-
-  friend std::ostream& operator<<(std::ostream& o, const restricted_scalar& x)  { return o << x.scalar_; }
-  friend bool operator<(const restricted_scalar& x, const restricted_scalar& y)  { return x.scalar_ < y.scalar_; }
-  friend bool operator==(const restricted_scalar& x, const restricted_scalar& y)  { return x.scalar_ == y.scalar_; }
+    /// @}
 
   protected:
     restricted_scalar() {}
     scalar scalar_;
+
+    friend std::ostream& operator<<(std::ostream& o, const restricted_scalar& x)  { return o << x.scalar_; }
+    friend bool operator<(const restricted_scalar& x, const restricted_scalar& y)  { return x.scalar_ < y.scalar_; }
+    friend bool operator==(const restricted_scalar& x, const restricted_scalar& y)  { return x.scalar_ == y.scalar_; }
 };
 
+/// @endcond
+
 }
+
 #endif // SCALAR_HPP

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/72b5f953/proton-c/bindings/cpp/include/proton/sender.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/sender.hpp b/proton-c/bindings/cpp/include/proton/sender.hpp
index a5835fd..17849770 100644
--- a/proton-c/bindings/cpp/include/proton/sender.hpp
+++ b/proton-c/bindings/cpp/include/proton/sender.hpp
@@ -21,6 +21,7 @@
  * under the License.
  *
  */
+
 #include "proton/export.hpp"
 #include "proton/delivery.hpp"
 #include "proton/link.hpp"
@@ -33,26 +34,31 @@ struct pn_connection_t;
 
 namespace proton {
 
-/// A sending link
+/// A link for sending messages.
 class sender : public link
 {
   public:
+    /// @cond INTERNAL
     sender(pn_link_t* s=0) : link(s) {}
+    /// @endcond
 
     /// Send a message on the link.
     PN_CPP_EXTERN delivery send(const message &m);
 
-    /** The number of deliveries that might be able to be sent if sufficient credit were
-        issued on the link.  See sender::offered().  Maintained by the application. */
+    /// @cond INTERNAL
+    /// XXX undiscussed
+    
+    /// The number of deliveries that might be able to be sent if
+    /// sufficient credit were issued on the link.  See
+    /// sender::offered().  Maintained by the application.
     PN_CPP_EXTERN int available();
 
-    /** Set the availability of deliveries for a sender. */
+    /// Set the availability of deliveries for a sender.
     PN_CPP_EXTERN void offered(int c);
 
-
+    /// @endcond
 };
 
-
 }
 
-#endif  /*!PROTON_CPP_SENDER_H*/
+#endif // PROTON_CPP_SENDER_H


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org


Mime
View raw message