qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jr...@apache.org
Subject qpid-proton git commit: PROTON-1543: Various improvements to the C++ API docs
Date Thu, 31 Aug 2017 12:27:01 GMT
Repository: qpid-proton
Updated Branches:
  refs/heads/master ba696d242 -> b60f093a1


PROTON-1543: Various improvements to the C++ API docs

 - Use 'Unsettled API' instead of 'Experimental'
 - Improve the map API docs
 - Document default values for endpoint options


Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo
Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/b60f093a
Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/b60f093a
Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/b60f093a

Branch: refs/heads/master
Commit: b60f093a1ca77f7d2de94fdac3a57b16a3765426
Parents: ba696d2
Author: Justin Ross <jross@apache.org>
Authored: Thu Aug 31 05:25:08 2017 -0700
Committer: Justin Ross <jross@apache.org>
Committed: Thu Aug 31 05:25:08 2017 -0700

----------------------------------------------------------------------
 proton-c/bindings/cpp/docs/io.md                |  2 +-
 .../cpp/include/proton/codec/common.hpp         |  4 +-
 .../cpp/include/proton/codec/decoder.hpp        |  2 +-
 .../cpp/include/proton/codec/encoder.hpp        |  2 +-
 .../cpp/include/proton/connection_options.hpp   | 31 ++++---
 .../bindings/cpp/include/proton/container.hpp   |  4 +-
 .../cpp/include/proton/error_condition.hpp      |  2 +-
 .../cpp/include/proton/internal/data.hpp        |  2 +-
 .../cpp/include/proton/io/connection_driver.hpp |  6 +-
 .../cpp/include/proton/io/link_namer.hpp        |  4 +-
 proton-c/bindings/cpp/include/proton/link.hpp   |  2 +-
 .../cpp/include/proton/listen_handler.hpp       |  2 +-
 proton-c/bindings/cpp/include/proton/map.hpp    | 85 ++++++++++++--------
 .../bindings/cpp/include/proton/message.hpp     | 12 +--
 .../cpp/include/proton/messaging_handler.hpp    |  4 +-
 .../bindings/cpp/include/proton/namespaces.hpp  |  4 +-
 .../bindings/cpp/include/proton/receiver.hpp    |  2 +-
 .../cpp/include/proton/receiver_options.hpp     | 34 ++++----
 proton-c/bindings/cpp/include/proton/sender.hpp |  2 +-
 .../cpp/include/proton/sender_options.hpp       | 11 ++-
 .../cpp/include/proton/session_options.hpp      |  4 +-
 proton-c/bindings/cpp/include/proton/source.hpp |  4 +-
 .../cpp/include/proton/source_options.hpp       | 23 +++---
 proton-c/bindings/cpp/include/proton/ssl.hpp    |  6 +-
 proton-c/bindings/cpp/include/proton/symbol.hpp |  8 +-
 .../cpp/include/proton/target_options.hpp       | 17 ++--
 proton-c/bindings/cpp/include/proton/url.hpp    |  2 +-
 .../bindings/cpp/include/proton/work_queue.hpp  | 24 +++---
 28 files changed, 169 insertions(+), 136 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/docs/io.md
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/docs/io.md b/proton-c/bindings/cpp/docs/io.md
index c0f7b02..2f380ce 100644
--- a/proton-c/bindings/cpp/docs/io.md
+++ b/proton-c/bindings/cpp/docs/io.md
@@ -1,6 +1,6 @@
 # IO integration {#io_page}
 
-**Experimental** - The `proton::io` interfaces are new and remain
+**Unsettled API** - The `proton::io` interfaces are new and remain
 subject to change.
 
 The `proton::io` namespace contains a service provider interface (SPI)

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/codec/common.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/codec/common.hpp b/proton-c/bindings/cpp/include/proton/codec/common.hpp
index e8d8ce5..61de8a5 100644
--- a/proton-c/bindings/cpp/include/proton/codec/common.hpp
+++ b/proton-c/bindings/cpp/include/proton/codec/common.hpp
@@ -27,7 +27,7 @@
 namespace proton {
 namespace codec {
 
-/// **Experimental** - Start encoding a complex type.
+/// **Unsettled API** - Start encoding a complex type.
 struct start {
     /// @cond INTERNAL
     /// XXX Document
@@ -50,7 +50,7 @@ struct start {
     /// @endcond
 };
 
-/// **Experimental** - Finish inserting or extracting a complex type.
+/// **Unsettled API** - Finish inserting or extracting a complex type.
 struct finish {};
 
 } // codec

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/codec/decoder.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/codec/decoder.hpp b/proton-c/bindings/cpp/include/proton/codec/decoder.hpp
index 3dc6d57..cf42f90 100644
--- a/proton-c/bindings/cpp/include/proton/codec/decoder.hpp
+++ b/proton-c/bindings/cpp/include/proton/codec/decoder.hpp
@@ -44,7 +44,7 @@ class value_base;
 
 namespace codec {
 
-/// **Experimental** - Stream-like decoder from AMQP bytes to C++
+/// **Unsettled API** - Stream-like decoder from AMQP bytes to C++
 /// values.
 ///
 /// For internal use only.

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/codec/encoder.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/codec/encoder.hpp b/proton-c/bindings/cpp/include/proton/codec/encoder.hpp
index 2610021..043e999 100644
--- a/proton-c/bindings/cpp/include/proton/codec/encoder.hpp
+++ b/proton-c/bindings/cpp/include/proton/codec/encoder.hpp
@@ -38,7 +38,7 @@ class value_base;
 
 namespace codec {
 
-/// **Experimental** - Stream-like encoder from C++ values to AMQP
+/// **Unsettled API** - Stream-like encoder from C++ values to AMQP
 /// bytes.
 ///
 /// For internal use only.

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/connection_options.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/connection_options.hpp b/proton-c/bindings/cpp/include/proton/connection_options.hpp
index c0ff457..62af5f3 100644
--- a/proton-c/bindings/cpp/include/proton/connection_options.hpp
+++ b/proton-c/bindings/cpp/include/proton/connection_options.hpp
@@ -86,26 +86,26 @@ class connection_options {
     /// Set the maximum frame size.  It is unlimited by default.
     PN_CPP_EXTERN connection_options& max_frame_size(uint32_t max);
 
-    /// Set the maximum number of open sessions.  The default value is 32767.
+    /// Set the maximum number of open sessions.  The default is 32767.
     PN_CPP_EXTERN connection_options& max_sessions(uint16_t max);
 
-    /// Set the idle timeout.  By default, none is set.
+    /// Set the idle timeout.  The default is no timeout.
     ///
-    /// If set, the local peer will disconnect if it does not receive
-    /// AMQP frames before the timeout expires.  This serves as
-    /// "heartbeating", a way to detect dead peers even in the
+    /// If set, the local peer will disconnect if it receives no AMQP
+    /// frames for an interval longer than `duration`.  Also known as
+    /// "heartbeating", this is a way to detect dead peers even in the
     /// presence of a live TCP connection.
     PN_CPP_EXTERN connection_options& idle_timeout(duration);
 
     /// Set the container ID.
     PN_CPP_EXTERN connection_options& container_id(const std::string& id);
 
-    /// Set the virtual host name for the connection. If making a
-    /// client connection by SSL/TLS, this name is also used for
-    /// certificate verification and Server Name Indication.  For
-    /// client connections, it defaults to the host name used to set
-    /// up the connection.  For server connections, it is not set by
-    /// default.
+    /// Set the virtual host name for the connection. For client
+    /// connections, it defaults to the host name used to set up the
+    /// connection.  For server connections, it is unset by default.
+    ///
+    /// If making a client connection by SSL/TLS, this name is also
+    /// used for certificate verification and Server Name Indication.
     PN_CPP_EXTERN connection_options& virtual_host(const std::string& name);
 
     /// Set the user name used to authenticate the connection.  It is
@@ -117,8 +117,7 @@ class connection_options {
     /// connection's identity is provided by the remote client.
     PN_CPP_EXTERN connection_options& user(const std::string&);
 
-    /// Set the password used to authenticate the connection.  It has
-    /// no default value.
+    /// Set the password used to authenticate the connection.
     ///
     /// This value is ignored if the connection is created by
     /// container::listen.
@@ -140,7 +139,7 @@ class connection_options {
     /// Enable or disable SASL.
     PN_CPP_EXTERN connection_options& sasl_enabled(bool);
 
-    /// Force the enabling of SASL mechanisms that disclose clear text
+    /// Force the enabling of SASL mechanisms that disclose cleartext
     /// passwords over the connection.  By default, such mechanisms
     /// are disabled.
     PN_CPP_EXTERN connection_options& sasl_allow_insecure_mechs(bool);
@@ -148,10 +147,10 @@ class connection_options {
     /// Specify the allowed mechanisms for use on the connection.
     PN_CPP_EXTERN connection_options& sasl_allowed_mechs(const std::string&);
 
-    /// **Experimental** - Set the SASL configuration name.
+    /// **Unsettled API** - Set the SASL configuration name.
     PN_CPP_EXTERN connection_options& sasl_config_name(const std::string&);
 
-    /// **Experimental** - Set the SASL configuration path.
+    /// **Unsettled API** - Set the SASL configuration path.
     PN_CPP_EXTERN connection_options& sasl_config_path(const std::string&);
 
     /// Update option values from values set in other.

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/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 64e52ad..d447abe 100644
--- a/proton-c/bindings/cpp/include/proton/container.hpp
+++ b/proton-c/bindings/cpp/include/proton/container.hpp
@@ -124,7 +124,7 @@ class PN_CPP_CLASS_EXTERN container {
     /// auto_stop is set by default when a new container is created.
     PN_CPP_EXTERN void auto_stop(bool);
 
-    /// **Experimental** - Stop the container with an error_condition
+    /// **Unsettled API** - Stop the container with an error_condition
     /// err.
     ///
     ///  - Abort all open connections and listeners.
@@ -133,7 +133,7 @@ class PN_CPP_CLASS_EXTERN container {
     ///  - run() will return in all threads.
     PN_CPP_EXTERN void stop(const error_condition& err);
 
-    /// **Experimental** - Stop the container with an empty error
+    /// **Unsettled API** - Stop the container with an empty error
     /// condition.
     ///
     /// @see stop(const error_condition&)

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/error_condition.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/error_condition.hpp b/proton-c/bindings/cpp/include/proton/error_condition.hpp
index fb0d461..159356e 100644
--- a/proton-c/bindings/cpp/include/proton/error_condition.hpp
+++ b/proton-c/bindings/cpp/include/proton/error_condition.hpp
@@ -50,7 +50,7 @@ class error_condition {
     /// Create an error condition with a name and description.
     PN_CPP_EXTERN error_condition(std::string name, std::string description);
 
-    /// **Experimental** - Create an error condition with name,
+    /// **Unsettled API** - Create an error condition with name,
     /// description, and informational properties.
     PN_CPP_EXTERN error_condition(std::string name, std::string description, proton::value
properties);
 

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/internal/data.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/internal/data.hpp b/proton-c/bindings/cpp/include/proton/internal/data.hpp
index 0e35486..97f900a 100644
--- a/proton-c/bindings/cpp/include/proton/internal/data.hpp
+++ b/proton-c/bindings/cpp/include/proton/internal/data.hpp
@@ -78,7 +78,7 @@ class data : public object<pn_data_t> {
 };
 /// @endcond
 
-/// **Experimental** - Save and restore codec state
+/// **Unsettled API** - Save and restore codec state
 ///
 /// A state_guard saves the state and restores it in the destructor
 /// unless cancel() is called.

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/io/connection_driver.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/io/connection_driver.hpp b/proton-c/bindings/cpp/include/proton/io/connection_driver.hpp
index f9774ac..a7e96fe 100644
--- a/proton-c/bindings/cpp/include/proton/io/connection_driver.hpp
+++ b/proton-c/bindings/cpp/include/proton/io/connection_driver.hpp
@@ -39,7 +39,7 @@ class proton_handler;
 
 namespace io {
 
-/// **Experimental** - Pointer to a mutable memory region with a size.
+/// **Unsettled API** - Pointer to a mutable memory region with a size.
 struct mutable_buffer {
     char* data;                 ///< Beginning of the buffered data.
     size_t size;                ///< Number of bytes in the buffer.
@@ -48,7 +48,7 @@ struct mutable_buffer {
     mutable_buffer(char* data_=0, size_t size_=0) : data(data_), size(size_) {}
 };
 
-/// **Experimental** - Pointer to a const memory region with a size.
+/// **Unsettled API** - Pointer to a const memory region with a size.
 struct const_buffer {
     const char* data;           ///< Beginning of the buffered data.
     size_t size;                ///< Number of bytes in the buffer.
@@ -57,7 +57,7 @@ struct const_buffer {
     const_buffer(const char* data_=0, size_t size_=0) : data(data_), size(size_) {}
 };
 
-/// **Experimental** - An AMQP driver for a single connection.
+/// **Unsettled API** - An AMQP driver for a single connection.
 ///
 /// io::connection_driver manages a single proton::connection and dispatches
 /// events to a proton::messaging_handler. It does no IO of its own, but allows you to

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/io/link_namer.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/io/link_namer.hpp b/proton-c/bindings/cpp/include/proton/io/link_namer.hpp
index a0eea67..e6d84ee 100644
--- a/proton-c/bindings/cpp/include/proton/io/link_namer.hpp
+++ b/proton-c/bindings/cpp/include/proton/io/link_namer.hpp
@@ -31,7 +31,7 @@ class connection;
 
 namespace io {
 
-/// **Experimental** - Generate default link names that are unique
+/// **Unsettled API** - Generate default link names that are unique
 /// within a container.  base_container provides a default
 /// implementation.
 class link_namer {
@@ -42,7 +42,7 @@ class link_namer {
     virtual std::string link_name() = 0;
 };
 
-/// *Experimental* - Set the link_namer to use on a connection.
+/// **Unsettled API** - Set the link_namer to use on a connection.
 PN_CPP_EXTERN void set_link_namer(connection&, link_namer&);
 
 } // io

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/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 8627ec9..eb28613 100644
--- a/proton-c/bindings/cpp/include/proton/link.hpp
+++ b/proton-c/bindings/cpp/include/proton/link.hpp
@@ -64,7 +64,7 @@ PN_CPP_CLASS_EXTERN link : public internal::object<pn_link_t> , public
endpoint
     /// Credit available on the link.
     PN_CPP_EXTERN int credit() const;
 
-    /// **Experimental** - True for a receiver if a drain cycle has
+    /// **Unsettled API** - True for a receiver if a drain cycle has
     /// been started and the corresponding `on_receiver_drain_finish`
     /// event is still pending.  True for a sender if the receiver has
     /// requested a drain of credit and the sender has unused credit.

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/listen_handler.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/listen_handler.hpp b/proton-c/bindings/cpp/include/proton/listen_handler.hpp
index 08d5e76..5373c54 100644
--- a/proton-c/bindings/cpp/include/proton/listen_handler.hpp
+++ b/proton-c/bindings/cpp/include/proton/listen_handler.hpp
@@ -27,7 +27,7 @@
 namespace proton {
 
 // XXX Discuss more
-/// **Experimental** - A handler for incoming connections.
+/// **Unsettled API** - A handler for incoming connections.
 ///
 /// Implement this interface and pass to proton::container::listen()
 /// to be notified of new connections.

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/map.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/map.hpp b/proton-c/bindings/cpp/include/proton/map.hpp
index 86948e5..dade948 100644
--- a/proton-c/bindings/cpp/include/proton/map.hpp
+++ b/proton-c/bindings/cpp/include/proton/map.hpp
@@ -1,5 +1,5 @@
-#ifndef PROTON_CPP_MAP_H
-#define PROTON_CPP_MAP_H
+#ifndef PROTON_MAP_HPP
+#define PROTON_MAP_HPP
 
 /*
  *
@@ -23,8 +23,7 @@
  */
 
 #include "./value.hpp"
-
-#include "internal/pn_unique_ptr.hpp"
+#include "./internal/pn_unique_ptr.hpp"
 
 #include <cstddef>
 
@@ -51,14 +50,16 @@ PN_CPP_EXTERN proton::codec::encoder& operator<<(proton::codec::encoder&
e, cons
 template <class K, class T>
 PN_CPP_EXTERN void swap(map<K,T>&, map<K,T>&);
 
-/// Used to access standard AMQP property, annotation and filter maps attached
-/// to proton::message and proton::source.
+/// A collection of key-value pairs.
 ///
-/// Provides only basic get()/set() operations for convenience.  For more
-/// complicated use (iteration, preserving order etc.) you should convert to a
-/// standard C++ map type such as std::map. See @ref message_properties.cpp
-/// and @ref types_page.
+/// Used to access standard AMQP property, annotation, and filter maps
+/// attached to proton::message and proton::source.
 ///
+/// This class provides only basic get() and put() operations for
+/// convenience.  For more complicated uses (iteration, preserving
+/// order, and so on), convert the value to a standard C++ map type
+/// such as `std::map`. See @ref message_properties.cpp and @ref
+/// types_page.
 template <class K, class T>
 class PN_CPP_CLASS_EXTERN map {
     template <class M, class U=void>
@@ -66,50 +67,69 @@ class PN_CPP_CLASS_EXTERN map {
             public internal::enable_if<codec::is_encodable_map<M,K,T>::value, U>
{};
 
  public:
-    /// @name Construct and assign
-    /// @{
+    /// Construct an empty map.
     PN_CPP_EXTERN map();
-    PN_CPP_EXTERN map(const map& cm);
-    PN_CPP_EXTERN map& operator=(const map& cm);
+
+    /// Copy a map.
+    PN_CPP_EXTERN map(const map&);
+
+    /// Copy a map.
+    PN_CPP_EXTERN map& operator=(const map&);
+
 #if PN_CPP_HAS_RVALUE_REFERENCES
+    /// Move a map.
     PN_CPP_EXTERN map(map&&);
+
+    /// Move a map.
     PN_CPP_EXTERN map& operator=(map&&);
 #endif
-    ///@}
     PN_CPP_EXTERN ~map();
 
-    /// Type-safe assign from a compatible map, e.g. std::map<K,T> - see @ref types_page
+    /// Type-safe assign from a compatible map, for instance
+    /// `std::map<K,T>`. See @ref types_page.
     template <class M>
-    typename assignable_map<M, map&>::type operator=(const M& x) { value(x);
return *this;}
+    typename assignable_map<M, map&>::type operator=(const M& x) { value(x);
return *this; }
 
     /// Copy from a proton::value.
-    /// @throw proton::conversion_error if x does not contain a compatible map.
+    ///
+    /// @throw proton::conversion_error if `x` does not contain a
+    /// compatible map.
     PN_CPP_EXTERN void value(const value& x);
-    /// Access as a proton::value containing an AMQP map
+
+    /// Access as a proton::value containing an AMQP map.
     PN_CPP_EXTERN proton::value& value();
-    /// Access as a proton::value containing an AMQP map
+
+    /// Access as a proton::value containing an AMQP map.
     PN_CPP_EXTERN const proton::value& value() const;
 
-    /// Get the map entry for key k, return T() if no such entry
+    /// Get the map entry for key `k`.  Return `T()` if there is no
+    /// such entry.
     PN_CPP_EXTERN T get(const K& k) const;
-    /// Put a map entry for key k.
+
+    /// Put a map entry for key `k`.
     PN_CPP_EXTERN void put(const K& k, const T& v);
-    /// Erase the map entry at k
+
+    /// Erase the map entry at `k`.
     PN_CPP_EXTERN size_t erase(const K& k);
-    /// True if there is a map entry for k
+
+    /// True if the map has an entry for `k`.
     PN_CPP_EXTERN bool exists(const K& k) const;
-    /// Number of map entries
+
+    /// Get the number of map entries.
     PN_CPP_EXTERN size_t size() const;
-    /// Clear the map
+
+    /// Remove all map entries.
     PN_CPP_EXTERN void clear();
-    /// True if the map is empty
+
+    /// True if the map has no entries.
     PN_CPP_EXTERN bool empty() const;
 
-    ///@cond INTERNAL
+    /// @cond INTERNAL
     explicit map(pn_data_t*);
     void reset(pn_data_t*);
+    /// @endcond
 
- private:
+  private:
     typedef map_type_impl<K,T> map_type;
     mutable internal::pn_unique_ptr<map_type> map_;
     mutable proton::value value_;
@@ -117,12 +137,13 @@ class PN_CPP_CLASS_EXTERN map {
     map_type& cache() const;
     proton::value& flush() const;
 
+    /// @cond INTERNAL
   friend PN_CPP_EXTERN proton::codec::decoder& operator>> <>(proton::codec::decoder&,
map&);
   friend PN_CPP_EXTERN proton::codec::encoder& operator<< <>(proton::codec::encoder&,
const map&);
   friend PN_CPP_EXTERN void swap<>(map&, map&);
-  /// @endcond
+    /// @endcond
 };
 
-} // namespace proton
+} // proton
 
-#endif // PROTON_CPP_MAP_H
+#endif // PROTON_MAP_HPP

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/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 a428c46..40aa98c 100644
--- a/proton-c/bindings/cpp/include/proton/message.hpp
+++ b/proton-c/bindings/cpp/include/proton/message.hpp
@@ -46,11 +46,11 @@ namespace proton {
 /// message.
 class message {
   public:
-    /// **Experimental** - A map of string keys and AMQP scalar
+    /// **Unsettled API** - A map of string keys and AMQP scalar
     /// values.
     typedef map<std::string, scalar> property_map;
 
-    /// **Experimental** - A map of AMQP annotation keys and AMQP
+    /// **Unsettled API** - A map of AMQP annotation keys and AMQP
     /// values.
     typedef map<annotation_key, value> annotation_map;
 
@@ -287,17 +287,17 @@ class message {
 
     /// @}
 
-    /// @name **Experimental** - Application properties
+    /// @name **Unsettled API** - Application properties
     /// @{
 
-    /// **Experimental** - Get the application properties map.  It can
+    /// **Unsettled API** - Get the application properties map.  It can
     /// be modified in place.
     PN_CPP_EXTERN property_map& properties();
 
-    /// **Experimental** - examine the application properties map.
+    /// **Unsettled API** - examine the application properties map.
     PN_CPP_EXTERN const property_map& properties() const;
 
-    /// @name **Experimental** - Annotations
+    /// @name **Unsettled API** - Annotations
     ///
     /// Normally used by messaging infrastructure, not applications.
     /// @{

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/messaging_handler.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/messaging_handler.hpp b/proton-c/bindings/cpp/include/proton/messaging_handler.hpp
index a5e2bdd..9c4d8f8 100644
--- a/proton-c/bindings/cpp/include/proton/messaging_handler.hpp
+++ b/proton-c/bindings/cpp/include/proton/messaging_handler.hpp
@@ -143,11 +143,11 @@ PN_CPP_CLASS_EXTERN messaging_handler {
     /// The sending peer settled a transfer.
     PN_CPP_EXTERN virtual void on_delivery_settle(delivery &d);
 
-    /// **Experimental** - The receiving peer has requested a drain of
+    /// **Unsettled API** - The receiving peer has requested a drain of
     /// remaining credit.
     PN_CPP_EXTERN virtual void on_sender_drain_start(sender &s);
     
-    /// **Experimental** - The credit outstanding at the time of the
+    /// **Unsettled API** - The credit outstanding at the time of the
     /// call to receiver::drain has been consumed or returned.
     PN_CPP_EXTERN virtual void on_receiver_drain_finish(receiver &r);
 

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/namespaces.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/namespaces.hpp b/proton-c/bindings/cpp/include/proton/namespaces.hpp
index 62b4913..d7b5cf9 100644
--- a/proton-c/bindings/cpp/include/proton/namespaces.hpp
+++ b/proton-c/bindings/cpp/include/proton/namespaces.hpp
@@ -23,7 +23,7 @@
 /// The main Proton namespace.
 namespace proton {
 
-/// **Experimental** - AMQP data encoding and decoding.
+/// **Unsettled API** - AMQP data encoding and decoding.
 ///
 /// You can use these classes on an experimental basis to create your
 /// own AMQP encodings for C++ types, but they may change in the
@@ -32,7 +32,7 @@ namespace proton {
 namespace codec {
 }
 
-/// **Experimental** - An SPI for multithreaded network IO.
+/// **Unsettled API** - An SPI for multithreaded network IO.
 namespace io {
 }
 

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/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 b995e6f..46e5c4d 100644
--- a/proton-c/bindings/cpp/include/proton/receiver.hpp
+++ b/proton-c/bindings/cpp/include/proton/receiver.hpp
@@ -63,7 +63,7 @@ PN_CPP_CLASS_EXTERN receiver : public link {
     /// the drain completes.
     PN_CPP_EXTERN void add_credit(uint32_t);
 
-    /// **Experimental** - Commence a drain cycle.  If there is
+    /// **Unsettled API** - Commence a drain cycle.  If there is
     /// positive credit, a request is sent to the sender to
     /// immediately use up all of the existing credit balance by
     /// sending messages that are immediately available and releasing

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/receiver_options.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/receiver_options.hpp b/proton-c/bindings/cpp/include/proton/receiver_options.hpp
index 413e4d4..1e43adb 100644
--- a/proton-c/bindings/cpp/include/proton/receiver_options.hpp
+++ b/proton-c/bindings/cpp/include/proton/receiver_options.hpp
@@ -62,42 +62,46 @@ class receiver_options {
     /// Copy options.
     PN_CPP_EXTERN receiver_options& operator=(const receiver_options&);
 
-    /// Merge with another option set
+    /// Merge with another option set.
     PN_CPP_EXTERN void update(const receiver_options& other);
 
-    /// Set a messaging_handler for receiver events only.
-    /// The handler is no longer in use when messaging_handler::on_receiver_close() is called.
+    /// Set a messaging_handler for receiver events only.  The handler
+    /// is no longer in use when
+    /// messaging_handler::on_receiver_close() is called.
     PN_CPP_EXTERN receiver_options& handler(class messaging_handler&);
 
-    /// Set the delivery mode on the receiver.
+    /// Set the delivery mode on the receiver.  The default is
+    /// delivery_mode::AT_LEAST_ONCE.
     PN_CPP_EXTERN receiver_options& delivery_mode(delivery_mode);
 
-    /// Automatically accept inbound messages that aren't otherwise
-    /// released, rejected, or modified (default is true).
+    /// Enable or disable automatic acceptance of messages that aren't
+    /// otherwise released, rejected, or modified.  It is enabled by
+    /// default.
     PN_CPP_EXTERN receiver_options& auto_accept(bool);
 
-    /// Automatically settle messages (default is true).
+    /// Enable or disable automatic settlement of messages.  It is
+    /// enabled by default.
     PN_CPP_EXTERN receiver_options& auto_settle(bool);
 
     /// Options for the source node of the receiver.
-    PN_CPP_EXTERN receiver_options& source(source_options &);
+    PN_CPP_EXTERN receiver_options& source(source_options&);
 
     /// Options for the target node of the receiver.
-    PN_CPP_EXTERN receiver_options& target(target_options &);
+    PN_CPP_EXTERN receiver_options& target(target_options&);
 
-    /// Set automated flow control to pre-fetch this many messages
-    /// (default is 10).  Set to zero to disable automatic credit
-    /// replenishing.
-    PN_CPP_EXTERN receiver_options& credit_window(int);
+    /// Automatically replenish credit for flow control up to `count`
+    /// messages.  The default is 10.  Set to zero to disable
+    /// automatic replenishment.
+    PN_CPP_EXTERN receiver_options& credit_window(int count);
 
-    /// @cond INTERNAL
   private:
     void apply(receiver &) const;
 
     class impl;
     internal::pn_unique_ptr<impl> impl_;
 
-    friend class receiver;
+    /// @cond INTERNAL
+  friend class receiver;
     /// @endcond
 };
 

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/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 b01f21c..7a1ae15 100644
--- a/proton-c/bindings/cpp/include/proton/sender.hpp
+++ b/proton-c/bindings/cpp/include/proton/sender.hpp
@@ -60,7 +60,7 @@ PN_CPP_CLASS_EXTERN sender : public link {
     /// Get the target node.
     PN_CPP_EXTERN class target target() const;
 
-    /// **Experimental** - Return all unused credit to the receiver in
+    /// **Unsettled API** - Return all unused credit to the receiver in
     /// response to a drain request.  Has no effect unless there has
     /// been a drain request and there is remaining credit to use or
     /// return.

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/sender_options.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/sender_options.hpp b/proton-c/bindings/cpp/include/proton/sender_options.hpp
index 9d7bb42..ea7f7d3 100644
--- a/proton-c/bindings/cpp/include/proton/sender_options.hpp
+++ b/proton-c/bindings/cpp/include/proton/sender_options.hpp
@@ -43,14 +43,13 @@ namespace proton {
 ///
 /// @code
 /// sender_options opts;
-/// opts.browsing(true);
+/// opts.delivery_mode(delivery_mode::AT_MOST_ONCE);
 /// 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.
-// XXX opts.browsing is not a good example here
 class sender_options {
   public:
     /// Create an empty set of options.
@@ -80,19 +79,19 @@ class sender_options {
     PN_CPP_EXTERN sender_options& auto_settle(bool);
 
     /// Options for the source node of the sender.
-    PN_CPP_EXTERN sender_options& source(const source_options &);
+    PN_CPP_EXTERN sender_options& source(const source_options&);
 
     /// Options for the receiver node of the receiver.
-    PN_CPP_EXTERN sender_options& target(const target_options &);
+    PN_CPP_EXTERN sender_options& target(const target_options&);
 
-    /// @cond INTERNAL
   private:
     void apply(sender&) const;
 
     class impl;
     internal::pn_unique_ptr<impl> impl_;
 
-    friend class sender;
+    /// @cond INTERNAL
+  friend class sender;
     /// @endcond
 };
 

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/session_options.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/session_options.hpp b/proton-c/bindings/cpp/include/proton/session_options.hpp
index eb47a89..9672c82 100644
--- a/proton-c/bindings/cpp/include/proton/session_options.hpp
+++ b/proton-c/bindings/cpp/include/proton/session_options.hpp
@@ -34,7 +34,6 @@ namespace proton {
 ///
 /// Normal value semantics: copy or assign creates a separate copy of
 /// the options.
-// XXX Does this need the CLASS_EXTERN stuff? - Add just for consistency
 class session_options {
   public:
     /// Create an empty set of options.
@@ -51,8 +50,9 @@ class session_options {
     /// Set a messaging_handler for the session.
     PN_CPP_EXTERN session_options& handler(class messaging_handler &);
 
-    /// @cond INTERNAL
     // Other useful session configuration TBD.
+
+    /// @cond INTERNAL
   private:
     void apply(session&) const;
 

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/source.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/source.hpp b/proton-c/bindings/cpp/include/proton/source.hpp
index 59963dd..52afd8f 100644
--- a/proton-c/bindings/cpp/include/proton/source.hpp
+++ b/proton-c/bindings/cpp/include/proton/source.hpp
@@ -40,7 +40,7 @@ namespace proton {
 /// @see proton::sender, proton::receiver, proton::target
 class source : public terminus {
   public:
-    /// **Experimental** - A map of AMQP symbol keys and filter
+    /// **Unsettled API** - A map of AMQP symbol keys and filter
     /// specifiers.
     typedef map<symbol, value> filter_map;
 
@@ -68,7 +68,7 @@ class source : public terminus {
     /// Get the distribution mode.
     PN_CPP_EXTERN enum distribution_mode distribution_mode() const;
 
-    /// **Experimental** - Obtain the set of message filters.
+    /// **Unsettled API** - Obtain the set of message filters.
     PN_CPP_EXTERN const filter_map& filters() const;
 
   private:

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/source_options.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/source_options.hpp b/proton-c/bindings/cpp/include/proton/source_options.hpp
index 19e3cdf..1b2876c 100644
--- a/proton-c/bindings/cpp/include/proton/source_options.hpp
+++ b/proton-c/bindings/cpp/include/proton/source_options.hpp
@@ -40,7 +40,6 @@ namespace proton {
 /// the options.
 class source_options {
   public:
-
     /// Create an empty set of options.
     PN_CPP_EXTERN source_options();
 
@@ -52,26 +51,32 @@ class source_options {
     /// Copy options.
     PN_CPP_EXTERN source_options& operator=(const source_options&);
 
-    /// Set the address for the source.  Ignored if dynamic is true.
+    /// Set the address for the source.  It is unset by default.  The
+    /// address is ignored if dynamic() is true.
     PN_CPP_EXTERN source_options& address(const std::string&);
 
-    /// Request a dynamically created node to be created by the remote peer.
-    /// Any specified source address is ignored.
+    /// Request that a node be dynamically created by the remote peer.
+    /// The default is false.  Any specified source address() is
+    /// ignored.
     PN_CPP_EXTERN source_options& dynamic(bool);
 
-    /// Control whether messsages are browsed or consumed.
+    /// Control whether messsages are browsed or consumed.  The
+    /// default is source::MOVE, meaning consumed.
     PN_CPP_EXTERN source_options& distribution_mode(enum source::distribution_mode);
 
-    /// Control the persistence of source state.
+    /// Control the persistence of the source node.  The default is
+    /// source::NONDURABLE, meaning non-persistent.
     PN_CPP_EXTERN source_options& durability_mode(enum source::durability_mode);
 
-    /// The expiry period after which the source is discarded.
+    /// The expiry period after which the source is discarded.  The
+    /// default is no timeout.
     PN_CPP_EXTERN source_options& timeout(duration);
 
-    /// Control when the clock for expiration begins.
+    /// Control when the clock for expiration begins.  The default is
+    /// source::LINK_CLOSE.
     PN_CPP_EXTERN source_options& expiry_policy(enum source::expiry_policy);
 
-    /// **Experimental** - Specify a filter mechanism on the source
+    /// **Unsettled API** - Specify a filter mechanism on the source
     /// that restricts message flow to a subset of the available
     /// messages.
     PN_CPP_EXTERN source_options& filters(const source::filter_map&);

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/ssl.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/ssl.hpp b/proton-c/bindings/cpp/include/proton/ssl.hpp
index c6c4c93..896c23d 100644
--- a/proton-c/bindings/cpp/include/proton/ssl.hpp
+++ b/proton-c/bindings/cpp/include/proton/ssl.hpp
@@ -92,7 +92,7 @@ class ssl {
     /// @endcond
 };
 
-/// **Experimental** - An SSL certificate.
+/// **Unsettled API** - An SSL certificate.
 class ssl_certificate {
   public:
     /// Create an SSL certificate.
@@ -141,7 +141,7 @@ class ssl_domain {
 
 }
 
-/// **Experimental** - SSL configuration for inbound connections.
+/// **Unsettled API** - SSL configuration for inbound connections.
 class ssl_server_options : private internal::ssl_domain {
   public:
     /// Server SSL options based on the supplied X.509 certificate
@@ -168,7 +168,7 @@ class ssl_server_options : private internal::ssl_domain {
     /// @endcond
 };
 
-/// **Experimental** - SSL configuration for outbound connections.
+/// **Unsettled API** - SSL configuration for outbound connections.
 class ssl_client_options : private internal::ssl_domain {
   public:
     /// Create SSL client options (no client certificate).

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/symbol.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/symbol.hpp b/proton-c/bindings/cpp/include/proton/symbol.hpp
index 303f350..3f60540 100644
--- a/proton-c/bindings/cpp/include/proton/symbol.hpp
+++ b/proton-c/bindings/cpp/include/proton/symbol.hpp
@@ -26,18 +26,18 @@
 
 namespace proton {
 
-/// A std::string that represents the AMQP symbol type.
+/// A `std::string` that represents the AMQP symbol type.
 ///
-/// A symbol can only contain 7-bit ASCII characters.
+/// A symbol can contain only 7-bit ASCII characters.
 class symbol : public std::string {
   public:
-    /// Construct from a std::string.
+    /// Construct from a `std::string`.
     symbol(const std::string& s=std::string()) : std::string(s) {}
 
     /// Construct from a C string.
     symbol(const char* s) : std::string(s) {}
 
-    /// Construct from any sequence of char.
+    /// Construct from any sequence of `char`.
     template<class Iter> symbol(Iter start, Iter finish) : std::string(start, finish)
{}
 };
 

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/target_options.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/target_options.hpp b/proton-c/bindings/cpp/include/proton/target_options.hpp
index 0f2245b..05249d0 100644
--- a/proton-c/bindings/cpp/include/proton/target_options.hpp
+++ b/proton-c/bindings/cpp/include/proton/target_options.hpp
@@ -51,20 +51,25 @@ class target_options {
     /// Copy options.
     PN_CPP_EXTERN target_options& operator=(const target_options&);
 
-    /// Set the address for the target.  Ignored if dynamic is true.
+    /// Set the address for the target.  It is unset by default.  The
+    /// address is ignored if dynamic() is true.
     PN_CPP_EXTERN target_options& address(const std::string& addr);
 
-    /// Request a dynamically created node to be created by the peer.
-    /// Any specified target address is ignored.
+    /// Request that a node be dynamically created by the remote peer.
+    /// The default is false.  Any specified target address() is
+    /// ignored.
     PN_CPP_EXTERN target_options& dynamic(bool);
 
-    /// Control the persistence of target state.
+    /// Control the persistence of the target node.  The default is
+    /// target::NONDURABLE, meaning non-persistent.
     PN_CPP_EXTERN target_options& durability_mode(enum target::durability_mode);
 
-    /// The expiry period after which the target is discarded.
+    /// The expiry period after which the target is discarded.  The
+    /// default is no timeout.
     PN_CPP_EXTERN target_options& timeout(duration);
 
-    /// Control when the clock for expiration begins.
+    /// Control when the clock for expiration begins.  The default is
+    /// target::LINK_CLOSE.
     PN_CPP_EXTERN target_options& expiry_policy(enum target::expiry_policy);
 
   private:

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/url.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/url.hpp b/proton-c/bindings/cpp/include/proton/url.hpp
index b94b24d..28f31e9 100644
--- a/proton-c/bindings/cpp/include/proton/url.hpp
+++ b/proton-c/bindings/cpp/include/proton/url.hpp
@@ -70,7 +70,7 @@ class url {
     /// @cond INTERNAL
     /// XXX I want to understand why this is important to keep.
     ///
-    /// **Experimental** - Parse `url_str` as an AMQP URL. If
+    /// **Unsettled API** - Parse `url_str` as an AMQP URL. If
     /// `defaults` is true, fill in defaults for missing values.
     /// Otherwise, return an empty string for missing values.
     ///

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/work_queue.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/work_queue.hpp b/proton-c/bindings/cpp/include/proton/work_queue.hpp
index 2d728fd..f5e60cd 100644
--- a/proton-c/bindings/cpp/include/proton/work_queue.hpp
+++ b/proton-c/bindings/cpp/include/proton/work_queue.hpp
@@ -37,21 +37,21 @@ struct pn_link_t;
 
 namespace proton {
 
-/// **Experimental** - Work to be queued on a @ref work_queue.  It can
+/// **Unsettled API** - Work to be queued on a @ref work_queue.  It can
 /// be created from a function that takes no parameters and returns no
 /// value.
 class work {
   public:
 #if PN_CPP_HAS_STD_FUNCTION
-    /// **Experimental**
+    /// **Unsettled API**
     work(void_function0& f): item_( [&f]() { f(); }) {}
 
-    /// **Experimental** - Construct a unit of work from a
+    /// **Unsettled API** - Construct a unit of work from a
     /// std::function.
     template <class T>
     work(T f): item_(f) {}
 
-    /// **Experimental**
+    /// **Unsettled API**
     void operator()() { item_(); }
 #else
     /// **Experimetnal**
@@ -71,7 +71,7 @@ class work {
 #endif
 };
 
-/// **Experimental** - A work queue for serial execution.
+/// **Unsettled API** - A work queue for serial execution.
 ///
 /// Event handler functions associated with a single
 /// proton::connection are called in sequence.  The connection's
@@ -94,15 +94,15 @@ class PN_CPP_CLASS_EXTERN work_queue {
     /// @endcond
 
   public:
-    /// **Experimental** - Create a work_queue.
+    /// **Unsettled API** - Create a work_queue.
     PN_CPP_EXTERN work_queue();
 
-    /// **Experimental** - Create a work_queue backed by `container`.
+    /// **Unsettled API** - Create a work_queue backed by `container`.
     PN_CPP_EXTERN work_queue(container&);
 
     PN_CPP_EXTERN ~work_queue();
 
-    /// **Experimental** - Add work to the work queue: f() will be
+    /// **Unsettled API** - Add work to the work queue: f() will be
     /// called serialised with other work in the queue: deferred and
     /// possibly in another thread.
     ///
@@ -110,7 +110,7 @@ class PN_CPP_CLASS_EXTERN work_queue {
     /// or f() cannot be injected for any other reason.
     PN_CPP_EXTERN bool add(work f);
 
-    /// **Experimental** - Add work to the work queue after duration:
+    /// **Unsettled API** - Add work to the work queue after duration:
     /// f() will be called after the duration serialised with other
     /// work in the queue: possibly in another thread.
     ///
@@ -363,19 +363,19 @@ void schedule_work(WQ wq, duration dn, F f, A a, B b, C c, D d) {
 // The C++11 version is *much* simpler and even so more general!
 // These definitions encompass everything in the C++03 section
 
-/// **Experimental**
+/// **Unsettled API**
 template <class WQ, class... Rest>
 bool schedule_work(WQ wq, Rest&&... r) {
     return wq->add(std::bind(std::forward<Rest>(r)...));
 }
 
-/// **Experimental**
+/// **Unsettled API**
 template <class WQ, class... Rest>
 void schedule_work(WQ wq, duration d, Rest&&... r) {
     wq->schedule(d, std::bind(std::forward<Rest>(r)...));
 }
 
-/// **Experimental**
+/// **Unsettled API**
 template <class... Rest>
 work make_work(Rest&&... r) {
     return std::bind(std::forward<Rest>(r)...);


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


Mime
View raw message