You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by jr...@apache.org on 2017/09/11 12:51:19 UTC
[1/2] qpid-proton git commit: PROTON-1543: Various copyedits and
additions to the C and C++ API docs
Repository: qpid-proton
Updated Branches:
refs/heads/master 7a5ded793 -> 363d337b5
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 5373c54..4ce20e9 100644
--- a/proton-c/bindings/cpp/include/proton/listen_handler.hpp
+++ b/proton-c/bindings/cpp/include/proton/listen_handler.hpp
@@ -24,6 +24,9 @@
#include "./fwd.hpp"
+/// @file
+/// @copybrief proton::listen_handler
+
namespace proton {
// XXX Discuss more
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/listener.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/listener.hpp b/proton-c/bindings/cpp/include/proton/listener.hpp
index c7f95a7..5f6ec6c 100644
--- a/proton-c/bindings/cpp/include/proton/listener.hpp
+++ b/proton-c/bindings/cpp/include/proton/listener.hpp
@@ -22,6 +22,9 @@
#include "./internal/export.hpp"
+/// @file
+/// @copybrief proton::listener
+
struct pn_listener_t;
namespace proton {
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 dade948..f9d524c 100644
--- a/proton-c/bindings/cpp/include/proton/map.hpp
+++ b/proton-c/bindings/cpp/include/proton/map.hpp
@@ -27,6 +27,9 @@
#include <cstddef>
+/// @file
+/// @copybrief proton::map
+
namespace proton {
namespace codec {
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 40aa98c..07d4132 100644
--- a/proton-c/bindings/cpp/include/proton/message.hpp
+++ b/proton-c/bindings/cpp/include/proton/message.hpp
@@ -36,6 +36,9 @@
#include <string>
#include <vector>
+/// @file
+/// @copybrief proton::message
+
struct pn_message_t;
namespace proton {
@@ -87,26 +90,26 @@ class message {
///
/// The message ID uniquely identifies a message within a
/// messaging system.
- PN_CPP_EXTERN void id(const message_id& id);
+ PN_CPP_EXTERN void id(const message_id&);
/// Get the message ID.
PN_CPP_EXTERN message_id id() const;
/// Set the user name or ID.
- PN_CPP_EXTERN void user(const std::string &user);
+ PN_CPP_EXTERN void user(const std::string&);
/// Get the user name or ID.
PN_CPP_EXTERN std::string user() 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 encode(std::vector<char>&) const;
/// Return encoded message as a byte vector.
PN_CPP_EXTERN std::vector<char> encode() const;
/// Decode from string data into the message.
- PN_CPP_EXTERN void decode(const std::vector<char> &bytes);
+ PN_CPP_EXTERN void decode(const std::vector<char>&);
/// @}
@@ -114,19 +117,19 @@ class message {
/// @{
/// Set the destination address.
- PN_CPP_EXTERN void to(const std::string &addr);
+ PN_CPP_EXTERN void to(const std::string&);
/// Get the destination address.
PN_CPP_EXTERN std::string to() const;
/// @cond INTERNAL
/// These are aliases for to()
- PN_CPP_EXTERN void address(const std::string &addr);
+ PN_CPP_EXTERN void address(const std::string&);
PN_CPP_EXTERN std::string address() const;
/// @endcond
/// Set the address for replies.
- PN_CPP_EXTERN void reply_to(const std::string &addr);
+ PN_CPP_EXTERN void reply_to(const std::string&);
/// Get the address for replies.
PN_CPP_EXTERN std::string reply_to() const;
@@ -152,31 +155,31 @@ class message {
PN_CPP_EXTERN value& body();
/// Set the subject.
- PN_CPP_EXTERN void subject(const std::string &s);
+ PN_CPP_EXTERN void subject(const std::string&);
/// Get the subject.
PN_CPP_EXTERN std::string subject() const;
/// Set the content type of the body.
- PN_CPP_EXTERN void content_type(const std::string &s);
+ PN_CPP_EXTERN void content_type(const std::string&);
/// Get the content type of the body.
PN_CPP_EXTERN std::string content_type() const;
/// Set the content encoding of the body.
- PN_CPP_EXTERN void content_encoding(const std::string &s);
+ PN_CPP_EXTERN void content_encoding(const std::string&);
/// Get the content encoding of the body.
PN_CPP_EXTERN std::string content_encoding() const;
/// Set the expiration time.
- PN_CPP_EXTERN void expiry_time(timestamp t);
+ PN_CPP_EXTERN void expiry_time(timestamp);
/// Get the expiration time.
PN_CPP_EXTERN timestamp expiry_time() const;
/// Set the creation time.
- PN_CPP_EXTERN void creation_time(timestamp t);
+ PN_CPP_EXTERN void creation_time(timestamp);
/// Get the creation time.
PN_CPP_EXTERN timestamp creation_time() const;
@@ -264,13 +267,13 @@ class message {
/// @{
/// Set the message group ID.
- PN_CPP_EXTERN void group_id(const std::string &s);
+ PN_CPP_EXTERN void group_id(const std::string&);
/// Get the message group ID.
PN_CPP_EXTERN std::string group_id() const;
/// Set the reply-to group ID.
- PN_CPP_EXTERN void reply_to_group_id(const std::string &s);
+ PN_CPP_EXTERN void reply_to_group_id(const std::string&);
/// Get the reply-to group ID.
PN_CPP_EXTERN std::string reply_to_group_id() const;
@@ -314,10 +317,10 @@ class message {
/// @cond INTERNAL
private:
struct impl;
- pn_message_t *pn_msg() const;
+ pn_message_t* pn_msg() const;
struct impl& impl() const;
- mutable pn_message_t *pn_msg_;
+ mutable pn_message_t* pn_msg_;
PN_CPP_EXTERN friend void swap(message&, message&);
/// @endcond
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 749337c..517a6b0 100644
--- a/proton-c/bindings/cpp/include/proton/message_id.hpp
+++ b/proton-c/bindings/cpp/include/proton/message_id.hpp
@@ -30,6 +30,9 @@
#include <string>
+/// @file
+/// @copybrief proton::message_id
+
namespace proton {
/// An AMQP message ID.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 4b1b920..e777d7d 100644
--- a/proton-c/bindings/cpp/include/proton/messaging_handler.hpp
+++ b/proton-c/bindings/cpp/include/proton/messaging_handler.hpp
@@ -25,8 +25,10 @@
#include "./fwd.hpp"
#include "./internal/export.hpp"
-namespace proton {
+/// @file
+/// @copybrief proton::messaging_handler
+namespace proton {
/// A handler for Proton messaging events.
///
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 d7b5cf9..9b756a7 100644
--- a/proton-c/bindings/cpp/include/proton/namespaces.hpp
+++ b/proton-c/bindings/cpp/include/proton/namespaces.hpp
@@ -20,19 +20,17 @@
* under the License.
*/
+/// @file
+/// Namespace declarations.
+
/// The main Proton namespace.
namespace proton {
/// **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
-/// future. For examples of use see the built-in encodings, for
-/// example in proton/vector.hpp or proton/map.hpp
namespace codec {
}
-/// **Unsettled API** - An SPI for multithreaded network IO.
+/// **Unsettled API** - Interfaces for IO integration.
namespace io {
}
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 46e5c4d..6c8137d 100644
--- a/proton-c/bindings/cpp/include/proton/receiver.hpp
+++ b/proton-c/bindings/cpp/include/proton/receiver.hpp
@@ -31,6 +31,9 @@
struct pn_link_t;
struct pn_session_t;
+/// @file
+/// @copybrief proton::receiver
+
namespace proton {
/// A channel for receiving messages.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 1e43adb..ae7a9fb 100644
--- a/proton-c/bindings/cpp/include/proton/receiver_options.hpp
+++ b/proton-c/bindings/cpp/include/proton/receiver_options.hpp
@@ -27,6 +27,9 @@
#include "./internal/pn_unique_ptr.hpp"
#include "./delivery_mode.hpp"
+/// @file
+/// @copybrief proton::receiver_options
+
namespace proton {
/// Options for creating a receiver.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/reconnect_options.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/reconnect_options.hpp b/proton-c/bindings/cpp/include/proton/reconnect_options.hpp
index abbd517..bc4e43a 100644
--- a/proton-c/bindings/cpp/include/proton/reconnect_options.hpp
+++ b/proton-c/bindings/cpp/include/proton/reconnect_options.hpp
@@ -30,20 +30,24 @@
#include <string>
#include <vector>
+/// @file
+/// @copybrief proton::reconnect_options
+
namespace proton {
-/// **Experimental** - Options that determine a series of delays to
-/// coordinate reconnection attempts. They may be open ended or
-/// limited in time. They may be evenly spaced or increasing at an
-/// exponential rate.
+/// **Unsettled API** - Options for reconnect and failover after
+/// connection loss.
+///
+/// These options determine a series of delays to coordinate
+/// reconnection attempts. They may be open-ended or limited in time.
+/// They may be evenly spaced or increasing at an exponential rate.
///
-/// Options can be "chained" (@see proton::connection_options).
+/// Options can be "chained". See @ref proton::connection_options.
///
/// Normal value semantics: copy or assign creates a separate copy of
/// the options.
class reconnect_options {
public:
-
/// Create an empty set of options.
PN_CPP_EXTERN reconnect_options();
@@ -55,21 +59,25 @@ class reconnect_options {
/// Copy options.
PN_CPP_EXTERN reconnect_options& operator=(const reconnect_options&);
- /// Base value for recurring delay (default is 10 milliseconds).
+ /// The base value for recurring delays. The default is 10
+ /// milliseconds.
PN_CPP_EXTERN reconnect_options& delay(duration);
- /// Scaling multiplier for successive reconnect delays (default is 2.0)
+ /// The scaling multiplier for successive reconnect delays. The
+ /// default is 2.0.
PN_CPP_EXTERN reconnect_options& delay_multiplier(float);
- /// Maximum delay between successive connect attempts (default
- /// duration::FOREVER, i.e. no limit)
+ /// The maximum delay between successive connect attempts. The
+ /// default duration::FOREVER, meaning no limit.
PN_CPP_EXTERN reconnect_options& max_delay(duration);
- /// Maximum reconnect attempts (default 0, meaning no limit)
+ /// The maximum number of reconnect attempts. The default is 0,
+ /// meaning no limit.
PN_CPP_EXTERN reconnect_options& max_attempts(int);
- /// Alternative connection urls used for failover
- PN_CPP_EXTERN reconnect_options& failover_urls(const std::vector<std::string>& urls);
+ /// Alternative connection URLs used for failover. There are none
+ /// by default.
+ PN_CPP_EXTERN reconnect_options& failover_urls(const std::vector<std::string>& conn_urls);
private:
class impl;
@@ -77,7 +85,7 @@ class reconnect_options {
/// @cond INTERNAL
friend class container;
- /// @endcond
+ /// @endcond
};
} // proton
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/returned.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/returned.hpp b/proton-c/bindings/cpp/include/proton/returned.hpp
index 45de4c4..84d3fca 100644
--- a/proton-c/bindings/cpp/include/proton/returned.hpp
+++ b/proton-c/bindings/cpp/include/proton/returned.hpp
@@ -29,9 +29,8 @@
#include "./receiver.hpp"
#include "./sender.hpp"
-
/// @file
-/// Return type for container functions
+/// @copybrief proton::returned
namespace proton {
@@ -39,25 +38,26 @@ namespace internal {
class returned_factory;
}
-/// Return type for container functions
+/// A return type for container methods.
///
-/// @note returned value is *thread-unsafe*.
-/// A single-threaded application can assign the returned<T> value to a plain T.
-/// A multi-threaded application *must* ignore the returned value, as it may already
-/// be invalid by the time the function returns. Multi-threaded applications
-/// can access the value in @ref messaging_handler functions.
+/// @note A `returned` value is *thread-unsafe*. A single-threaded
+/// application can assign the `returned<T>` value to a plain `T`. A
+/// multithreaded application *must* ignore the returned value because
+/// it may already be invalid by the time the function
+/// returns. Multithreaded applications can safely access the value
+/// inside @ref messaging_handler functions.
///
template <class T>
class PN_CPP_CLASS_EXTERN returned
{
public:
/// Copy operator required to return a value
- /// @note thread safe
+ /// @note Thread-safe
PN_CPP_EXTERN returned(const returned<T>&);
/// Convert to the proton::object
///
- /// @note **Thread unsafe** do not use in a multi-threaded application.
+ /// @note **Thread-unsafe** - Do not use in a multithreaded application.
PN_CPP_EXTERN operator T() const;
private:
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 3857f06..e381dc7 100644
--- a/proton-c/bindings/cpp/include/proton/sasl.hpp
+++ b/proton-c/bindings/cpp/include/proton/sasl.hpp
@@ -30,6 +30,9 @@
#include <string>
+/// @file
+/// @copybrief proton::sasl
+
namespace proton {
/// SASL information.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 99236c3..870ce0d 100644
--- a/proton-c/bindings/cpp/include/proton/scalar.hpp
+++ b/proton-c/bindings/cpp/include/proton/scalar.hpp
@@ -24,6 +24,9 @@
#include <proton/type_compat.h>
+/// @file
+/// @copybrief proton::scalar
+
namespace proton {
/// A holder for an instance of any scalar AMQP type.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/scalar_base.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/scalar_base.hpp b/proton-c/bindings/cpp/include/proton/scalar_base.hpp
index ca3161a..c88f0a8 100644
--- a/proton-c/bindings/cpp/include/proton/scalar_base.hpp
+++ b/proton-c/bindings/cpp/include/proton/scalar_base.hpp
@@ -40,6 +40,9 @@
#include <string>
#include <typeinfo>
+/// @file
+/// @copybrief proton::scalar_base
+
namespace proton {
class scalar_base;
@@ -53,7 +56,7 @@ namespace internal {
template<class T> T get(const scalar_base& s);
}
-/// Base class for scalar types.
+/// The base class for scalar types.
class scalar_base : private internal::comparable<scalar_base> {
public:
/// AMQP type of data stored in the scalar
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 7a1ae15..840032c 100644
--- a/proton-c/bindings/cpp/include/proton/sender.hpp
+++ b/proton-c/bindings/cpp/include/proton/sender.hpp
@@ -27,6 +27,9 @@
#include "./link.hpp"
#include "./tracker.hpp"
+/// @file
+/// @copybrief proton::sender
+
struct pn_link_t;
struct pn_session_t;
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 ea7f7d3..235513b 100644
--- a/proton-c/bindings/cpp/include/proton/sender_options.hpp
+++ b/proton-c/bindings/cpp/include/proton/sender_options.hpp
@@ -27,6 +27,9 @@
#include "./internal/pn_unique_ptr.hpp"
#include "./delivery_mode.hpp"
+/// @file
+/// @copybrief proton::sender_options
+
namespace proton {
/// Options for creating a sender.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/session.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/session.hpp b/proton-c/bindings/cpp/include/proton/session.hpp
index c66aa05..78a1fd4 100644
--- a/proton-c/bindings/cpp/include/proton/session.hpp
+++ b/proton-c/bindings/cpp/include/proton/session.hpp
@@ -30,6 +30,9 @@
#include <string>
+/// @file
+/// @copybrief proton::session
+
struct pn_session_t;
namespace proton {
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 9672c82..515a798 100644
--- a/proton-c/bindings/cpp/include/proton/session_options.hpp
+++ b/proton-c/bindings/cpp/include/proton/session_options.hpp
@@ -26,6 +26,9 @@
#include "./internal/export.hpp"
#include "./internal/pn_unique_ptr.hpp"
+/// @file
+/// @copybrief proton::session_options
+
namespace proton {
/// Options for creating a session.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 52afd8f..18b5ed7 100644
--- a/proton-c/bindings/cpp/include/proton/source.hpp
+++ b/proton-c/bindings/cpp/include/proton/source.hpp
@@ -31,6 +31,9 @@
#include <string>
+/// @file
+/// @copybrief proton::source
+
struct pn_terminus_t;
namespace proton {
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 1b2876c..92804c3 100644
--- a/proton-c/bindings/cpp/include/proton/source_options.hpp
+++ b/proton-c/bindings/cpp/include/proton/source_options.hpp
@@ -29,6 +29,9 @@
#include <string>
+/// @file
+/// @copybrief proton::source_options
+
namespace proton {
/// Options for creating a source node for a sender or receiver.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 896c23d..8186f71 100644
--- a/proton-c/bindings/cpp/include/proton/ssl.hpp
+++ b/proton-c/bindings/cpp/include/proton/ssl.hpp
@@ -28,6 +28,9 @@
#include <string>
+/// @file
+/// @copybrief proton::ssl
+
namespace proton {
namespace internal {
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 3f60540..e1847ba 100644
--- a/proton-c/bindings/cpp/include/proton/symbol.hpp
+++ b/proton-c/bindings/cpp/include/proton/symbol.hpp
@@ -24,9 +24,12 @@
#include <string>
+/// @file
+/// @copybrief proton::symbol
+
namespace proton {
-/// A `std::string` that represents the AMQP symbol type.
+/// A string that represents the AMQP symbol type.
///
/// A symbol can contain only 7-bit ASCII characters.
class symbol : public std::string {
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/target.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/target.hpp b/proton-c/bindings/cpp/include/proton/target.hpp
index 746133a..448a340 100644
--- a/proton-c/bindings/cpp/include/proton/target.hpp
+++ b/proton-c/bindings/cpp/include/proton/target.hpp
@@ -28,6 +28,9 @@
#include <string>
+/// @file
+/// @copybrief proton::target
+
struct pn_terminus_t;
namespace proton {
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 05249d0..428465f 100644
--- a/proton-c/bindings/cpp/include/proton/target_options.hpp
+++ b/proton-c/bindings/cpp/include/proton/target_options.hpp
@@ -29,6 +29,9 @@
#include <string>
+/// @file
+/// @copybrief proton::target_options
+
namespace proton {
/// Options for creating a target node for a sender or receiver.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/terminus.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/terminus.hpp b/proton-c/bindings/cpp/include/proton/terminus.hpp
index e339b84..760dcd4 100644
--- a/proton-c/bindings/cpp/include/proton/terminus.hpp
+++ b/proton-c/bindings/cpp/include/proton/terminus.hpp
@@ -29,6 +29,9 @@
#include <string>
+/// @file
+/// @copybrief proton::terminus
+
struct pn_link_t;
struct pn_terminus_t;
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/thread_safe.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/thread_safe.hpp b/proton-c/bindings/cpp/include/proton/thread_safe.hpp
index 7fc1bcd..5dcf2cd 100644
--- a/proton-c/bindings/cpp/include/proton/thread_safe.hpp
+++ b/proton-c/bindings/cpp/include/proton/thread_safe.hpp
@@ -20,7 +20,7 @@
* under the License.
*/
-// DEPRECATED: This file is no longer used and will be removed,
-// you should not include it in your code.
+/// @file
+/// **Deprecated**
#endif // PROTON_THREAD_SAFE_HPP
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/timestamp.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/timestamp.hpp b/proton-c/bindings/cpp/include/proton/timestamp.hpp
index ea578bb..b67d3b9 100644
--- a/proton-c/bindings/cpp/include/proton/timestamp.hpp
+++ b/proton-c/bindings/cpp/include/proton/timestamp.hpp
@@ -24,6 +24,9 @@
#include <proton/type_compat.h>
+/// @file
+/// @copybrief proton::timestamp
+
namespace proton {
/// A 64-bit timestamp in milliseconds since the Unix epoch.
@@ -31,19 +34,19 @@ namespace proton {
/// The dawn of the Unix epoch was 00:00:00 (UTC), 1 January 1970.
class timestamp : private internal::comparable<timestamp> {
public:
- /// A numeric type holding a milliseconds value.
+ /// A numeric type holding a value in milliseconds.
typedef int64_t numeric_type;
/// The current wall-clock time.
PN_CPP_EXTERN static timestamp now();
- /// Construct from milliseconds.
+ /// Construct from a value in milliseconds.
explicit timestamp(numeric_type ms = 0) : ms_(ms) {}
- /// Assign from milliseconds.
+ /// Assign a value in milliseconds.
timestamp& operator=(numeric_type ms) { ms_ = ms; return *this; }
- /// Get milliseconds.
+ /// Get the value in milliseconds.
numeric_type milliseconds() const { return ms_; }
private:
@@ -61,7 +64,7 @@ inline duration operator-(timestamp t0, timestamp t1) { return duration(t0.milli
inline timestamp operator+(duration d, timestamp ts) { return ts + d; }
/// @}
-/// Printable format.
+/// Print a timestamp.
PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, timestamp);
} // proton
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/tracker.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/tracker.hpp b/proton-c/bindings/cpp/include/proton/tracker.hpp
index 408b04d..b3e6811 100644
--- a/proton-c/bindings/cpp/include/proton/tracker.hpp
+++ b/proton-c/bindings/cpp/include/proton/tracker.hpp
@@ -25,6 +25,9 @@
#include "./internal/export.hpp"
#include "./transfer.hpp"
+/// @file
+/// @copybrief proton::tracker
+
struct pn_delivery_t;
namespace proton {
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/transfer.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/transfer.hpp b/proton-c/bindings/cpp/include/proton/transfer.hpp
index 80b0860..7727b54 100644
--- a/proton-c/bindings/cpp/include/proton/transfer.hpp
+++ b/proton-c/bindings/cpp/include/proton/transfer.hpp
@@ -28,6 +28,9 @@
#include <proton/disposition.h>
+/// @file
+/// @copybrief proton::transfer
+
struct pn_delivery_t;
namespace proton {
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/transport.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/transport.hpp b/proton-c/bindings/cpp/include/proton/transport.hpp
index 614eff2..0687e24 100644
--- a/proton-c/bindings/cpp/include/proton/transport.hpp
+++ b/proton-c/bindings/cpp/include/proton/transport.hpp
@@ -26,6 +26,9 @@
#include "./internal/export.hpp"
#include "./internal/object.hpp"
+/// @file
+/// @copybrief proton::transport
+
struct pn_transport_t;
namespace proton {
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/type_id.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/type_id.hpp b/proton-c/bindings/cpp/include/proton/type_id.hpp
index 4460eb6..2cca6f3 100644
--- a/proton-c/bindings/cpp/include/proton/type_id.hpp
+++ b/proton-c/bindings/cpp/include/proton/type_id.hpp
@@ -23,8 +23,7 @@
*/
/// @file
-///
-/// Type-identifiers for AMQP types.
+/// Type IDs for AMQP data types.
#include "./internal/export.hpp"
@@ -73,7 +72,7 @@ PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, type_id);
/// the names of the types.
PN_CPP_EXTERN void assert_type_equal(type_id want, type_id got);
-/// @name Test the properties of a type_id.
+/// @name Functions to test the properties of a type ID
/// @{
inline bool type_id_is_signed_int(type_id t) { return t == BYTE || t == SHORT || t == INT || t == LONG; }
inline bool type_id_is_unsigned_int(type_id t) { return t == UBYTE || t == USHORT || t == UINT || t == ULONG; }
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/types.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/types.hpp b/proton-c/bindings/cpp/include/proton/types.hpp
index f541b13..7d88bfa 100644
--- a/proton-c/bindings/cpp/include/proton/types.hpp
+++ b/proton-c/bindings/cpp/include/proton/types.hpp
@@ -23,98 +23,10 @@
*/
/// @file
-///
-/// Include the definitions of all proton types used to represent AMQP
-/// types.
+/// Proton types used to represent AMQP types.
// TODO aconway 2016-03-15: described types, described arrays.
-/** @page types_page AMQP and C++ types
-
-An AMQP message body can hold binary data using any encoding you
-like. AMQP also defines its own encoding and types. The AMQP encoding
-is often used in message bodies because it is supported by AMQP
-libraries on many languages and platforms. You also need to use the
-AMQP types to set and examine message properties.
-
-## Scalar types
-
-Each type is identified by a proton::type_id.
-
-C++ type | AMQP type_id | Description
---------------------|----------------------|-----------------------
-bool | proton::BOOLEAN | Boolean true or false
-uint8_t | proton::UBYTE | 8-bit unsigned byte
-int8_t | proton::BYTE | 8-bit signed byte
-uint16_t | proton::USHORT | 16-bit unsigned integer
-int16_t | proton::SHORT | 16-bit signed integer
-uint32_t | proton::UINT | 32-bit unsigned integer
-int32_t | proton::INT | 32-bit signed integer
-uint64_t | proton::ULONG | 64-bit unsigned integer
-int64_t | proton::LONG | 64-bit signed integer
-wchar_t | proton::CHAR | 32-bit unicode code point
-float | proton::FLOAT | 32-bit binary floating point
-double | proton::DOUBLE | 64-bit binary floating point
-proton::timestamp | proton::TIMESTAMP | 64-bit signed milliseconds since 00:00:00 (UTC), 1 January 1970.
-proton::decimal32 | proton::DECIMAL32 | 32-bit decimal floating point
-proton::decimal64 | proton::DECIMAL64 | 64-bit decimal floating point
-proton::decimal128 | proton::DECIMAL128 | 128-bit decimal floating point
-proton::uuid | proton::UUID | 128-bit universally-unique identifier
-std::string | proton::STRING | UTF-8 encoded Unicode string
-proton::symbol | proton::SYMBOL | 7-bit ASCII encoded string
-proton::binary | proton::BINARY | Variable-length binary data
-
-## Holder types
-
-proton::message::body() and other message-related data can contain different
-types of data at run-time. There are two "holder" types provided to hold
-run-time typed data:
-
-- proton::scalar can hold a scalar value of any type.
-- proton::value can hold any AMQP value, scalar or compound.
-
-You can set the value in a holder by assignment, and use the proton::get() and
-proton::coerce() templates extract data in a type-safe way. Holders also provide
-functions to query the type of value they contain.
-
-## Compound types
-
-C++ type | AMQP type_id | Description
---------------------|----------------------|-----------------------
-See below | proton::ARRAY | Sequence of values of the same type
-See below | proton::LIST | Sequence of values of mixed types
-See below | proton::MAP | Map of key-value pairs
-
-A proton::value containing a proton::ARRAY can convert to and from C++ sequences
-of the corresponding C++ type: std::vector, std::deque, std::list, and
-std::forward_list.
-
-proton::LIST converts to and from sequences of proton::value or
-proton::scalar, which can hold mixed types of data.
-
-proton::MAP converts to and from std::map, std::unordered_map, and
-sequences of std::pair.
-
-For example you can decode a message body with any AMQP MAP as follows:
-
- proton::message m = ...;
- std::map<proton::value, proton::value> map;
- proton::get(m.body(), map);
-
-You can encode a message body with a map of string to uint64_t like this:
-
- std::unordered_map<std::string, uint64_t> map;
- map["foo"] = 123;
- m.body() = map;
-
-## Include files
-
-`proton/types.hpp` includes all available type definitions and
-conversions. Alternatively, you can selectively include the .hpp files you
-want, see @ref types.hpp.
-
-*/
-
#include "./internal/config.hpp"
#include "./annotation_key.hpp"
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/types_fwd.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/types_fwd.hpp b/proton-c/bindings/cpp/include/proton/types_fwd.hpp
index a2d2508..e71f477 100644
--- a/proton-c/bindings/cpp/include/proton/types_fwd.hpp
+++ b/proton-c/bindings/cpp/include/proton/types_fwd.hpp
@@ -23,7 +23,7 @@
*/
/// @file
-/// Forward declarations for all C++ types used by Proton to represent AMQP types.
+/// Forward declarations for Proton types used to represent AMQP types.
#include "./internal/config.hpp"
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 28f31e9..848e2d1 100644
--- a/proton-c/bindings/cpp/include/proton/url.hpp
+++ b/proton-c/bindings/cpp/include/proton/url.hpp
@@ -30,8 +30,13 @@
#include <iosfwd>
#include <string>
+/// @file
+/// @copybrief proton::url
+
namespace proton {
+/// **Deprecated**
+///
/// An error encountered during URL parsing.
struct
PN_CPP_CLASS_EXTERN url_error : public error {
@@ -41,6 +46,8 @@ PN_CPP_CLASS_EXTERN url_error : public error {
/// @endcond
};
+/// **Deprecated**
+///
/// A URL parser.
///
/// Proton URLs take the form
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/uuid.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/uuid.hpp b/proton-c/bindings/cpp/include/proton/uuid.hpp
index a60c944..464d7a7 100644
--- a/proton-c/bindings/cpp/include/proton/uuid.hpp
+++ b/proton-c/bindings/cpp/include/proton/uuid.hpp
@@ -28,6 +28,9 @@
#include <string>
#include <iosfwd>
+/// @file
+/// @copybrief proton::uuid
+
namespace proton {
/// A 16-byte universally unique identifier.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/value.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/value.hpp b/proton-c/bindings/cpp/include/proton/value.hpp
index 9ced1af..071f812 100644
--- a/proton-c/bindings/cpp/include/proton/value.hpp
+++ b/proton-c/bindings/cpp/include/proton/value.hpp
@@ -32,6 +32,9 @@
#include <iosfwd>
+/// @file
+/// @copybrief proton::value
+
namespace proton {
namespace internal {
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 f5e60cd..a4244c7 100644
--- a/proton-c/bindings/cpp/include/proton/work_queue.hpp
+++ b/proton-c/bindings/cpp/include/proton/work_queue.hpp
@@ -35,11 +35,15 @@ struct pn_connection_t;
struct pn_session_t;
struct pn_link_t;
+/// @file
+/// @copybrief proton::work_queue
+
namespace proton {
-/// **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.
+/// **Unsettled API** - A work item for a @ref work_queue "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
@@ -71,21 +75,21 @@ class work {
#endif
};
-/// **Unsettled API** - A work queue for serial execution.
+/// **Unsettled API** - A context for thread-safe execution of work.
///
-/// Event handler functions associated with a single
-/// proton::connection are called in sequence. The connection's
-/// proton::work_queue allows you to "inject" extra @ref work from any
-/// thread, and have it executed in the same sequence.
+/// Event-handler functions associated with a single
+/// `proton::connection` are called in sequence. The connection's
+/// `proton::work_queue` allows you to "inject" extra @ref work from
+/// any thread and have it executed in the same sequence.
///
-/// You may also create arbitrary proton::work_queue objects backed by
-/// a @ref container that allow other objects to have their own
+/// You may also create arbitrary `proton::work_queue` objects backed
+/// by a @ref container that allow other objects to have their own
/// serialised work queues that can have work injected safely from
/// other threads. The @ref container ensures that the work is
/// correctly serialised.
///
-/// The @ref work class represents the work to be queued and can be
-/// created from a function that takes no parameters and returns no
+/// The `proton::work` class represents the work to be queued and can
+/// be created from a function that takes no parameters and returns no
/// value.
class PN_CPP_CLASS_EXTERN work_queue {
/// @cond INTERNAL
@@ -94,30 +98,33 @@ class PN_CPP_CLASS_EXTERN work_queue {
/// @endcond
public:
- /// **Unsettled API** - Create a work_queue.
+ /// **Unsettled API** - Create a work queue.
PN_CPP_EXTERN work_queue();
- /// **Unsettled API** - Create a work_queue backed by `container`.
+ /// **Unsettled API** - Create a work queue backed by a container.
PN_CPP_EXTERN work_queue(container&);
PN_CPP_EXTERN ~work_queue();
- /// **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.
+ /// **Unsettled API** - Add work `fn` to the work queue.
+
+ /// Work `fn` will be called serially with other work in the queue.
+ /// The work may be deferred and executed in another thread.
///
- /// @return true if f() has or will be called, false if the event_loop is ended
- /// or f() cannot be injected for any other reason.
- PN_CPP_EXTERN bool add(work f);
+ /// @return true if `fn` has been or will be called; false if the
+ /// event loops is ended or `fn` cannot be injected for any other
+ /// reason.
+ PN_CPP_EXTERN bool add(work fn);
- /// **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.
+ /// **Unsettled API** - Add work `fn` to the work queue after a
+ /// duration.
+ ///
+ /// Scheduled execution is "best effort". It may not be possible
+ /// to inject the work after the elapsed duration. There will be
+ /// no indication of this.
///
- /// The scheduled execution is "best effort" and it is possible that after the elapsed duration
- /// the work will not be able to be injected into the serialised context - there will be no
- /// indication of this.
- PN_CPP_EXTERN void schedule(duration, work);
+ /// @copydetails add()
+ PN_CPP_EXTERN void schedule(duration, work fn);
private:
PN_CPP_EXTERN static work_queue& get(pn_connection_t*);
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/docs/api/index.md
----------------------------------------------------------------------
diff --git a/proton-c/docs/api/index.md b/proton-c/docs/api/index.md
deleted file mode 100644
index 18accd4..0000000
--- a/proton-c/docs/api/index.md
+++ /dev/null
@@ -1,36 +0,0 @@
-# Introduction {#index}
-
-This is the C API for the Proton AMQP protocol engine. It allows you
-to write client and server applications that send and receive AMQP
-messages.
-
-## Core
-
-@ref core is a collection of types and functions representing AMQP
-concepts. Together they form a "protocol engine" API to create AMQP
-connections and links, handle @ref event "events", and send and
-receive @ref message "messages".
-
-## Types
-
-@ref types contains C data types, including @ref amqp\_types and @ref
-api\_types.
-
-## Codec
-
-@ref codec has functions for AMQP data encoding and decoding.
-
-## Proactor
-
-The @ref proactor is a portable, proactive, asynchronous API for
-single- or multithreaded applications. It associates AMQP @ref
-connection "connections" with network connections (@ref transport
-"transports") and allows one or more threads to handle @ref event
-"events".
-
-## Low-level IO integration
-
-The @ref connection\_driver Connection Driver is a low-level SPI to feed byte
-streams from any source to the protocol engine. You can use it to integrate
-Proton directly with a foreign event loop or IO library, or to implement your
-own @ref proactor to transparently replace Proton's IO layer.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/docs/api/io.md
----------------------------------------------------------------------
diff --git a/proton-c/docs/api/io.md b/proton-c/docs/api/io.md
new file mode 100644
index 0000000..7cc071f
--- /dev/null
+++ b/proton-c/docs/api/io.md
@@ -0,0 +1,16 @@
+## IO integration {#io_page}
+
+**Unsettled API** - The IO interfaces are new and remain subject to
+change.
+
+The @ref proactor is a portable, proactive, asynchronous API for
+single- or multithreaded applications. It associates AMQP @ref
+connection "connections" with network connections (@ref transport
+"transports") and allows one or more threads to handle @ref event
+"events".
+
+The @ref connection\_driver is a low-level SPI to feed byte streams
+from any source to the protocol engine. You can use it to integrate
+Proton directly with a foreign event loop or IO library, or to
+implement your own @ref proactor to transparently replace Proton's IO
+layer.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/docs/api/main.md
----------------------------------------------------------------------
diff --git a/proton-c/docs/api/main.md b/proton-c/docs/api/main.md
new file mode 100644
index 0000000..74cdb76
--- /dev/null
+++ b/proton-c/docs/api/main.md
@@ -0,0 +1,33 @@
+# Introduction {#mainpage}
+
+The Qpid Proton C API enables writing clients and servers that send
+and receive messages using the AMQP protocol. It is part of the
+[Qpid Proton](https://qpid.apache.org/proton/index.html) suite of
+messaging APIs.
+
+## Modules
+
+The @ref core module is a collection of types and functions
+representing AMQP concepts and key elements of the API. Together they
+form a "protocol engine" API to create AMQP @ref connection
+"connections" and @ref link "links", handle @ref event "events", and
+send and receive @ref message "messages".
+
+The @ref types module contains C types and functions for handling
+AMQP- and API-specific data types.
+
+The @ref codec module has functions for AMQP data encoding and
+decoding.
+
+The @ref io module contains interfaces for integrating with
+platform-native network IO. See @ref io_page for more information.
+
+## Conventions
+
+Elements of the API marked as **Unsettled API**, including any
+elements contained within them, are still evolving and thus are
+subject to change. They are available to use, but newer versions of
+Proton may require changes to your application source code.
+
+Elements marked **Deprecated** are slated for removal in a future
+release.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/docs/api/user.doxygen.in
----------------------------------------------------------------------
diff --git a/proton-c/docs/api/user.doxygen.in b/proton-c/docs/api/user.doxygen.in
index 686ac59..5db865f 100644
--- a/proton-c/docs/api/user.doxygen.in
+++ b/proton-c/docs/api/user.doxygen.in
@@ -19,7 +19,7 @@
# Project options
-PROJECT_NAME = "Qpid Proton C API"
+PROJECT_NAME = "Qpid Proton C"
PROJECT_NUMBER = @PN_VERSION_MAJOR@.@PN_VERSION_MINOR@.@PN_VERSION_POINT@
OUTPUT_DIRECTORY = .
OUTPUT_LANGUAGE = English
@@ -35,8 +35,7 @@ HIDE_COMPOUND_REFERENCE = YES
HIDE_SCOPE_NAMES = YES
MAX_INITIALIZER_LINES = 0
ALPHABETICAL_INDEX = NO
-# Use declaration order, don't alphabetize
-SORT_MEMBER_DOCS = NO
+SORT_MEMBER_DOCS = NO
# Redefine protected as private and strip out the PN_EXTERN and
# PNX_EXTERN macros
@@ -75,11 +74,12 @@ EXAMPLE_RECURSIVE = YES
# View and list options
+DISABLE_INDEX = YES
GENERATE_TREEVIEW = YES
GENERATE_TODOLIST = NO
GENERATE_TESTLIST = NO
GENERATE_BUGLIST = NO
-GENERATE_DEPRECATEDLIST = YES
+GENERATE_DEPRECATEDLIST = NO
IGNORE_PREFIX = pn_ PN_
# Configuration options related to the output format
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/include/proton/codec.h
----------------------------------------------------------------------
diff --git a/proton-c/include/proton/codec.h b/proton-c/include/proton/codec.h
index 8f96774..bcbbbf0 100644
--- a/proton-c/include/proton/codec.h
+++ b/proton-c/include/proton/codec.h
@@ -45,7 +45,6 @@ extern "C" {
* @ingroup amqp_types
*/
typedef enum {
-
/**
* The NULL AMQP type.
*/
@@ -570,7 +569,7 @@ PN_EXTERN ssize_t pn_data_decode(pn_data_t *data, const char *bytes, size_t size
* ::pn_data_exit() may be used to return to the current level in the
* tree and put more values.
*
- * @code
+ * @code
* pn_data_t *data = pn_data(0);
* ...
* pn_data_put_list(data);
@@ -580,7 +579,7 @@ PN_EXTERN ssize_t pn_data_decode(pn_data_t *data, const char *bytes, size_t size
* pn_data_put_int(data, 3);
* pn_data_exit(data);
* ...
- * @endcode
+ * @endcode
*
* @param data a pn_data_t object
* @return zero on success or an error code on failure
@@ -591,7 +590,7 @@ PN_EXTERN int pn_data_put_list(pn_data_t *data);
* Puts an empty map value into a pn_data_t. Elements may be filled by
* entering the map node and putting alternating key value pairs.
*
- * @code
+ * @code
* pn_data_t *data = pn_data(0);
* ...
* pn_data_put_map(data);
@@ -600,7 +599,7 @@ PN_EXTERN int pn_data_put_list(pn_data_t *data);
* pn_data_put_string(data, pn_bytes(5, "value"));
* pn_data_exit(data);
* ...
- * @endcode
+ * @endcode
*
* @param data a pn_data_t object
* @return zero on success or an error code on failure
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/include/proton/condition.h
----------------------------------------------------------------------
diff --git a/proton-c/include/proton/condition.h b/proton-c/include/proton/condition.h
index 631a678..8c5cfe3 100644
--- a/proton-c/include/proton/condition.h
+++ b/proton-c/include/proton/condition.h
@@ -41,7 +41,7 @@ extern "C" {
*/
/**
- * An AMQP Condition object. Conditions hold exceptional information
+ * An AMQP Condition object. Conditions hold exception information
* pertaining to the closing of an AMQP endpoint such as a Connection,
* Session, or Link. Conditions also hold similar information
* pertaining to deliveries that have reached terminal states.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/include/proton/connection.h
----------------------------------------------------------------------
diff --git a/proton-c/include/proton/connection.h b/proton-c/include/proton/connection.h
index 748cd13..d08a2c9 100644
--- a/proton-c/include/proton/connection.h
+++ b/proton-c/include/proton/connection.h
@@ -52,7 +52,6 @@ extern "C" {
/**
* The local @link pn_state_t endpoint state @endlink is active.
*/
-
#define PN_LOCAL_ACTIVE (2)
/**
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/include/proton/connection_driver.h
----------------------------------------------------------------------
diff --git a/proton-c/include/proton/connection_driver.h b/proton-c/include/proton/connection_driver.h
index 237dde6..82c7eb1 100644
--- a/proton-c/include/proton/connection_driver.h
+++ b/proton-c/include/proton/connection_driver.h
@@ -25,6 +25,9 @@
*
* @copybrief connection_driver
*
+ * @addtogroup connection_driver
+ * @{
+ *
* Associate a @ref connection and @ref transport with AMQP byte
* streams from any source.
*
@@ -32,22 +35,22 @@
* - generate ::pn_event_t events for your application to handle
* - encode resulting AMQP output bytes for some output byte stream
*
- * The pn_connection_driver_() functions provide a simplified API and
+ * The `pn_connection_driver_*` functions provide a simplified API and
* extra logic to use ::pn_connection_t and ::pn_transport_t as a
* unit. You can also access them directly for features that do not
- * have pn_connection_driver_() functions.
+ * have `pn_connection_driver_*` functions.
*
- * The driver buffers events and data, you should run it until
+ * The driver buffers events and data. You should run it until
* pn_connection_driver_finished() is true, to ensure all reading,
- * writing and event handling (including ERROR and FINAL events) is
- * finished.
+ * writing, and event handling (including `ERROR` and `FINAL` events)
+ * is finished.
*
* ## Error handling
*
- * The pn_connection_driver_*() functions do not return an error
- * code. IO errors set the transport condition and are returned as a
- * PN_TRANSPORT_ERROR. The integration code can set errors using
- * pn_connection_driver_errorf().
+ * The `pn_connection_driver_*` functions do not return an error
+ * code. IO errors are set on the transport condition and are returned
+ * as a `PN_TRANSPORT_ERROR`. The integration code can set errors
+ * using pn_connection_driver_errorf().
*
* ## IO patterns
*
@@ -57,7 +60,7 @@
* all available events before calling
* pn_connection_driver_read_buffer() and check that `size` is
* non-zero before starting a blocking or asynchronous read call. A
- * `read` started while there are unprocessed CLOSE events in the
+ * `read` started while there are unprocessed `CLOSE` events in the
* buffer may never complete.
*
* AMQP is a full-duplex, asynchronous protocol. The "read" and
@@ -66,12 +69,9 @@
* ## Thread safety
*
* The @ref connection_driver types are not thread safe, but each
- * connection and its associated types forms an independent
+ * connection and its associated types form an independent
* unit. Different connections can be processed concurrently by
* different threads.
- *
- * @addtogroup connection_driver
- * @{
*/
#include <proton/import_export.h>
@@ -112,8 +112,9 @@ typedef struct pn_connection_driver_t {
*/
PN_EXTERN int pn_connection_driver_init(pn_connection_driver_t*, pn_connection_t*, pn_transport_t*);
-/** Force binding of the transport.
- * This happens automatically after the PN_CONNECTION_INIT is processed.
+/**
+ * Force binding of the transport. This happens automatically after
+ * the PN_CONNECTION_INIT is processed.
*
* @return PN_STATE_ERR if the transport is already bound.
*/
@@ -265,7 +266,6 @@ PN_EXTERN pn_connection_driver_t* pn_event_batch_connection_driver(pn_event_batc
*/
#define PN_TRANSPORT_READ_CLOSED PN_TRANSPORT_TAIL_CLOSED
-
/**
* @}
*/
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/include/proton/disposition.h
----------------------------------------------------------------------
diff --git a/proton-c/include/proton/disposition.h b/proton-c/include/proton/disposition.h
index de438bf..c35314a 100644
--- a/proton-c/include/proton/disposition.h
+++ b/proton-c/include/proton/disposition.h
@@ -34,14 +34,16 @@ extern "C" {
/**
* @file
*
- * Delivery state
+ * @copybrief delivery
*
* @addtogroup delivery
* @{
*/
/**
- * Dispositions record the current state and/or final outcome of a
+ * A delivery state.
+ *
+ * Dispositions record the current state or final outcome of a
* transfer. Every delivery contains both a local and remote
* disposition. The local disposition holds the local state of the
* delivery, and the remote disposition holds the last known remote
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/include/proton/event.h
----------------------------------------------------------------------
diff --git a/proton-c/include/proton/event.h b/proton-c/include/proton/event.h
index 2db0373..fc2e5ea 100644
--- a/proton-c/include/proton/event.h
+++ b/proton-c/include/proton/event.h
@@ -540,7 +540,7 @@ PN_EXTERN pn_record_t *pn_event_attachments(pn_event_t *event);
PN_EXTERN struct pn_condition_t *pn_event_condition(pn_event_t *event);
/**
- * **Experimental** - A batch of events that must be handled in sequence.
+ * **Unsettled API** - A batch of events that must be handled in sequence.
* Call pn_event_batch_next() in a loop until it returns NULL to extract
* the events.
*/
@@ -552,7 +552,7 @@ typedef struct pn_event_batch_t pn_event_batch_t;
*/
/**
- * **Experimental** - Remove the next event from the batch and return
+ * **Unsettled API** - Remove the next event from the batch and return
* it. NULL means the batch is empty. The returned event pointer is
* valid until pn_event_batch_next() is called again on the same
* batch.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/include/proton/link.h
----------------------------------------------------------------------
diff --git a/proton-c/include/proton/link.h b/proton-c/include/proton/link.h
index d52e6e7..792181e 100644
--- a/proton-c/include/proton/link.h
+++ b/proton-c/include/proton/link.h
@@ -647,7 +647,7 @@ PN_EXTERN ssize_t pn_link_recv(pn_link_t *receiver, char *bytes, size_t n);
PN_EXTERN bool pn_link_draining(pn_link_t *receiver);
/**
- * **Experimental** - Get the maximum message size for a link.
+ * **Unsettled API** - Get the maximum message size for a link.
*
* A zero maximum message size means the size is unlimited.
*
@@ -657,7 +657,7 @@ PN_EXTERN bool pn_link_draining(pn_link_t *receiver);
PN_EXTERN uint64_t pn_link_max_message_size(pn_link_t *link);
/**
- * **Experimental** - Set the maximum message size for a link.
+ * **Unsettled API** - Set the maximum message size for a link.
*
* A zero maximum message size means the size is unlimited.
*
@@ -667,7 +667,7 @@ PN_EXTERN uint64_t pn_link_max_message_size(pn_link_t *link);
PN_EXTERN void pn_link_set_max_message_size(pn_link_t *link, uint64_t size);
/**
- * **Experimental** - Get the remote view of the maximum message size for a link.
+ * **Unsettled API** - Get the remote view of the maximum message size for a link.
*
* A zero maximum message size means the size is unlimited.
*
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/include/proton/listener.h
----------------------------------------------------------------------
diff --git a/proton-c/include/proton/listener.h b/proton-c/include/proton/listener.h
index d06adb9..974b6df 100644
--- a/proton-c/include/proton/listener.h
+++ b/proton-c/include/proton/listener.h
@@ -30,18 +30,15 @@ extern "C" {
/**
* @file
- * @copydoc listener
*
- * @defgroup listener Listener
- * @ingroup proactor
- *
- * **Experimental** - A listener for incoming connections for the @ref proactor.
- *
- * @note Thread safety: Listener has the same thread-safety rules as a @ref core
- * object; calls to a single listener must be serialized with the exception of
- * pn_listener_close()
+ * @copybrief listener
*
+ * @addtogroup listener
* @{
+ *
+ * @note Thread safety: Listener has the same thread-safety rules as a
+ * @ref core object. Calls to a single listener must be serialized
+ * with the exception of pn_listener_close().
*/
/**
@@ -77,14 +74,15 @@ PNP_EXTERN pn_condition_t *pn_listener_condition(pn_listener_t *l);
/**
* @deprecated
*
- * Get the application context that is associated with a listener.
+ * **Deprecated** - Get the application context that is associated
+ * with a listener.
*/
PNP_EXTERN void *pn_listener_get_context(pn_listener_t *listener);
/**
* @deprecated
*
- * Set a new application context for a listener.
+ * **Deprecated** - Set a new application context for a listener.
*/
PNP_EXTERN void pn_listener_set_context(pn_listener_t *listener, void *context);
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/include/proton/netaddr.h
----------------------------------------------------------------------
diff --git a/proton-c/include/proton/netaddr.h b/proton-c/include/proton/netaddr.h
index 9cde766..33cf37e 100644
--- a/proton-c/include/proton/netaddr.h
+++ b/proton-c/include/proton/netaddr.h
@@ -25,20 +25,20 @@
/**
* @file
- * Use to examine the network address of proactor connections.
*
- * @addtogroup proactor
+ * @copybrief pn_netaddr_t
*
+ * @addtogroup proactor
* @{
*/
/**
- * Network address of a proactor transport.
+ * **Unsettled API** - The network address of a proactor transport.
*/
typedef struct pn_netaddr_t pn_netaddr_t;
/**
- * Format a network address as a human-readable string in buf.
+ * Format a network address as a human-readable string in `buf`.
*
* @return the length of the string (excluding trailing '\0'), if >= size then
* the address was truncated.
@@ -46,7 +46,7 @@ typedef struct pn_netaddr_t pn_netaddr_t;
PNP_EXTERN int pn_netaddr_str(const pn_netaddr_t *addr, char *buf, size_t size);
/**
- * Get the local address of a transport. Return NULL if not available.
+ * Get the local address of a transport. Return `NULL` if not available.
*/
PNP_EXTERN const pn_netaddr_t *pn_netaddr_local(pn_transport_t *t);
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/include/proton/proactor.h
----------------------------------------------------------------------
diff --git a/proton-c/include/proton/proactor.h b/proton-c/include/proton/proactor.h
index 8d5ff0e..206b6d9 100644
--- a/proton-c/include/proton/proactor.h
+++ b/proton-c/include/proton/proactor.h
@@ -31,38 +31,41 @@ extern "C" {
/**
* @file
- * @copydoc proactor
*
- * @addtogroup proactor Proactor
- *
- * The proactor associates an abstract AMQP protocol @ref connection with a
- * concrete IO @ref transport implementation for outgoing and incoming
- * connections. pn_proactor_wait() returns @ref proactor_events to application
- * threads for handling.
- *
- * The @ref pn_proactor* functions are thread-safe, but to handle @ref proactor_events you
- * must also use the @ref core APIs which are not. @ref core objects associated
- * with different connections can be used concurrently, but objects associated
- * with a single connection cannot.
- *
- * The proactor *serializes* @ref proactor_events for each connection - it never returns
- * @ref proactor_events for the same connection concurrently in different
- * threads. Event-handling code can safely use any @ref core object obtained
- * from the current event. You can attach application data to @ref core objects
- * (for example with pn_connection_attachments()).
- *
- * pn_connection_wake() allows any thread to "wake up" a connection. It causes
- * pn_proactor_wait() to return a @ref PN_CONNECTION_WAKE event that is
- * serialized with the connection's other @ref proactor_events. You can use this to implement
- * communication between different connections, or from non-proactor threads.
- *
- * Serialization and pn_connection_wake() simplify building applications with a
- * shared thread pool, which serialize work per connection. Many other
- * variations are possible, but you are responsible for any additional
- * synchronization needed.
+ * @copybrief proactor
*
* @addtogroup proactor
* @{
+ *
+ * The proactor associates an abstract AMQP protocol @ref connection
+ * with a concrete IO @ref transport implementation for outgoing and
+ * incoming connections. pn_proactor_wait() returns @ref
+ * proactor_events to application threads for handling.
+ *
+ * The `pn_proactor*` functions are thread-safe, but to handle @ref
+ * proactor_events you must also use the @ref core APIs, which are
+ * not. @ref core objects associated with different connections can be
+ * used concurrently, but objects associated with a single connection
+ * can only be used from their own thread.
+ *
+ * The proactor *serializes* @ref proactor_events for each connection
+ * - it never returns @ref proactor_events for the same connection
+ * concurrently in different threads. Event-handling code can safely
+ * use any @ref core object obtained from the current event. You can
+ * attach application data to @ref core objects (for example with
+ * pn_connection_attachments()).
+ *
+ * pn_connection_wake() allows any thread to "wake up" a
+ * connection. It causes pn_proactor_wait() to return a @ref
+ * PN_CONNECTION_WAKE event that is serialized with the connection's
+ * other @ref proactor_events. You can use this to implement
+ * communication between different connections, or from non-proactor
+ * threads.
+ *
+ * Serialization and pn_connection_wake() simplify building
+ * applications with a shared thread pool, which serialize work per
+ * connection. Many other variations are possible, but you are
+ * responsible for any additional synchronization needed.
*/
/**
@@ -96,7 +99,7 @@ PNP_EXTERN void pn_proactor_free(pn_proactor_t *proactor);
* Bind @p connection to a new @ref transport connected to @p addr.
* Errors are returned as @ref PN_TRANSPORT_CLOSED events by pn_proactor_wait().
*
- * @note Thread safe.
+ * @note Thread-safe
*
* @param[in] proactor the proactor object
*
@@ -119,7 +122,7 @@ PNP_EXTERN void pn_proactor_connect(pn_proactor_t *proactor, pn_connection_t *co
* Start listening for incoming connections.
* Errors are returned as @ref proactor_events by pn_proactor_wait().
*
- * @note Thread safe.
+ * @note Thread-safe
*
* @param[in] proactor the proactor object
*
@@ -151,7 +154,7 @@ PNP_EXTERN void pn_proactor_listen(pn_proactor_t *proactor, pn_listener_t *liste
* Note the proactor remains active, connections and listeners created after a call to
* pn_proactor_disconnect() are not affected by it.
*
- * @note Thread safe.
+ * @note Thread-safe
*
* @param proactor the proactor
*
@@ -171,7 +174,7 @@ PNP_EXTERN void pn_proactor_disconnect(pn_proactor_t *proactor, pn_condition_t *
*
* pn_proactor_get() is a non-blocking version of this call.
*
- * @note Thread Safe.
+ * @note Thread-safe
*
* @return a non-empty batch of events that must be processed in sequence.
*
@@ -182,7 +185,7 @@ PNP_EXTERN pn_event_batch_t *pn_proactor_wait(pn_proactor_t *proactor);
* Return @ref proactor_events if any are available immediately. If not, return NULL.
* If the return value is not NULL, the behavior is the same as pn_proactor_wait()
*
- * @note Thread Safe.
+ * @note Thread-safe
*/
PNP_EXTERN pn_event_batch_t *pn_proactor_get(pn_proactor_t *proactor);
@@ -218,7 +221,7 @@ PNP_EXTERN void pn_proactor_interrupt(pn_proactor_t *proactor);
* is delivered will cancel the previous timeout and deliver an event only after
* the new timeout.
*
- * @note Thread safe
+ * @note Thread-safe
*/
PNP_EXTERN void pn_proactor_set_timeout(pn_proactor_t *proactor, pn_millis_t timeout);
@@ -226,7 +229,7 @@ PNP_EXTERN void pn_proactor_set_timeout(pn_proactor_t *proactor, pn_millis_t tim
* Cancel the pending timeout set by pn_proactor_set_timeout(). Does nothing
* if no timeout is set.
*
- * @note Thread safe
+ * @note Thread-safe
*/
PNP_EXTERN void pn_proactor_cancel_timeout(pn_proactor_t *proactor);
@@ -239,11 +242,12 @@ PNP_EXTERN void pn_proactor_cancel_timeout(pn_proactor_t *proactor);
* call pn_connection_free(), either directly or indirectly by re-using @p
* connection in another call to pn_proactor_connect() or pn_proactor_listen().
*
- * @note **NOT** thread safe, call from connection event handler.
+ * @note **Not thread-safe**. Call this function from a connection
+ * event handler.
*
* @note If @p connection does not belong to a proactor, this call does nothing.
*
- * @note This has nothing to do with pn_connection_release()
+ * @note This has nothing to do with pn_connection_release().
*/
PNP_EXTERN void pn_proactor_release_connection(pn_connection_t *connection);
@@ -257,14 +261,14 @@ PNP_EXTERN void pn_proactor_release_connection(pn_connection_t *connection);
*
* @note If @p connection does not belong to a proactor, this call does nothing.
*
- * @note Thread safe
+ * @note Thread-safe
*/
PNP_EXTERN void pn_connection_wake(pn_connection_t *connection);
/**
* Return the proactor associated with a connection.
*
- * @note Not Thread safe.
+ * @note **Not thread-safe**
*
* @return the proactor or NULL if the connection does not belong to a proactor.
*/
@@ -273,7 +277,7 @@ PNP_EXTERN pn_proactor_t *pn_connection_proactor(pn_connection_t *connection);
/**
* Return the proactor associated with an event.
*
- * @note Not Thread safe.
+ * @note **Not thread-safe**
*
* @return the proactor or NULL if the connection does not belong to a proactor.
*/
@@ -289,16 +293,21 @@ PNP_EXTERN pn_proactor_t *pn_event_proactor(pn_event_t *event);
* of a message. Such a timestamp should use the real time in milliseconds
* since the epoch.
*
- * @note Thread safe.
+ * @note Thread-safe
*/
PNP_EXTERN pn_millis_t pn_proactor_now(void);
/**
- * @defgroup proactor_events Events
+ * @}
+ */
+
+/**
+ * pn_proactor_wait() returns a subset of the event types defined by
+ * @ref pn_event_type_t. The PN_REACTOR_\*, PN_SELECTABLE_\*, and
+ * PN_\*_FINAL events are not returned.
*
- * **Experimental** - Events returned by pn_proactor_wait().
- * pn_proactor_wait() returns a subset of the event types defined by @ref pn_event_type_t.
- * The PN_REACTOR_..., PN_SELECTABLE_... and PN_..._FINAL events are not returned.
+ * @addtogroup proactor_events
+ * @{
*
* Enumeration | Brief description, see @ref pn_event_type_t for more
* :-- | :--
@@ -341,7 +350,6 @@ PNP_EXTERN pn_millis_t pn_proactor_now(void);
* @ref PN_CONNECTION_WAKE | @copybrief PN_CONNECTION_WAKE
*
* @}
- * @}
*/
#ifdef __cplusplus
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/include/proton/transport.h
----------------------------------------------------------------------
diff --git a/proton-c/include/proton/transport.h b/proton-c/include/proton/transport.h
index 89b6fad..5c88bab 100644
--- a/proton-c/include/proton/transport.h
+++ b/proton-c/include/proton/transport.h
@@ -67,42 +67,45 @@ typedef void (*pn_tracer_t)(pn_transport_t *transport, const char *message);
#define PN_TRACE_OFF (0)
/**
- * Log raw binary data into/out of the transport.
+ * Log raw binary data going in and out of the transport.
*/
#define PN_TRACE_RAW (1)
/**
- * Log frames into/out of the transport.
+ * Log protocol frames going in and out of the transport.
*/
#define PN_TRACE_FRM (2)
/**
- * Log driver related events, e.g. initialization, end of stream, etc.
+ * Log driver-related events. For example, initialization, end of
+ * stream, and so on.
*/
#define PN_TRACE_DRV (4)
/**
- * Log events
+ * Log events.
*/
#define PN_TRACE_EVT (8)
/**
* Factory for creating a transport.
+ *
* A transport is used by a connection to interface with the network.
* There can only be one connection associated with a transport. See
* pn_transport_bind().
*
- * Initially a transport is configured to be a client transport. Use pn_transport_set_server()
- * to configure the transport as a server transport.
+ * Initially a transport is configured to be a client transport. Use
+ * pn_transport_set_server() to configure the transport as a server
+ * transport.
*
* A client transport initiates outgoing connections.
*
- * A client transport must be configured with the protocol layers to use and cannot
- * configure itself automatically.
+ * A client transport must be configured with the protocol layers to
+ * use and cannot configure itself automatically.
*
- * A server transport accepts incoming connections. It can automatically
- * configure itself to include the various protocol layers depending on
- * the incoming protocol headers.
+ * A server transport accepts incoming connections. It can
+ * automatically configure itself to include the various protocol
+ * layers depending on the incoming protocol headers.
*
* @return pointer to new transport
*/
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/include/proton/types.h
----------------------------------------------------------------------
diff --git a/proton-c/include/proton/types.h b/proton-c/include/proton/types.h
index 5504e8d..dfae34b 100644
--- a/proton-c/include/proton/types.h
+++ b/proton-c/include/proton/types.h
@@ -32,88 +32,100 @@
* @copybrief types
*
* @defgroup core Core
- * @brief Core protocol entities and event handling
+ * @brief Core protocol entities and event handling.
*
* @defgroup connection Connection
- * @brief A channel for communication between two peers on a network
+ * @brief A connection to a remote AMQP peer.
* @ingroup core
*
* @defgroup session Session
- * @brief A container of links
+ * @brief A container of links.
* @ingroup core
*
* @defgroup link Link
- * @brief A channel for transferring messages
+ * @brief A channel for transferring messages.
* @ingroup core
*
* @defgroup terminus Terminus
- * @brief A source or target for messages
+ * @brief A source or target for messages.
* @ingroup core
*
* @defgroup message Message
- * @brief A mutable holder of application content
+ * @brief A mutable holder of application content.
* @ingroup core
*
* @defgroup delivery Delivery
- * @brief A message transfer
+ * @brief A message transfer.
* @ingroup core
*
* @defgroup condition Condition
- * @brief An endpoint error state
+ * @brief An endpoint error state.
* @ingroup core
*
* @defgroup event Event
- * @brief Protocol and transport events
+ * @brief Protocol and transport events.
* @ingroup core
*
* @defgroup transport Transport
- * @brief A network channel supporting an AMQP connection
+ * @brief A network channel supporting an AMQP connection.
* @ingroup core
*
* @defgroup sasl SASL
- * @brief SASL secure transport layer
+ * @brief SASL secure transport layer.
* @ingroup core
*
* @defgroup ssl SSL
- * @brief SSL secure transport layer
+ * @brief SSL secure transport layer.
* @ingroup core
*
* @defgroup error Error
- * @brief A Proton API error
+ * @brief A Proton API error.
* @ingroup core
*
* @defgroup types Types
- * @brief AMQP and API data types
+ * @brief AMQP and API data types.
*
* @defgroup amqp_types AMQP data types
- * @brief AMQP data types
+ * @brief AMQP data types.
* @ingroup types
*
* @defgroup api_types API data types
- * @brief Additional data types used in the API
+ * @brief Additional data types used in the API.
* @ingroup types
*
* @defgroup codec Codec
- * @brief AMQP data encoding and decoding
+ * @brief AMQP data encoding and decoding.
*
* @defgroup data Data
- * @brief A data structure for AMQP data
+ * @brief A data structure for AMQP data.
* @ingroup codec
*
+ * @defgroup io IO
+ * @brief **Unsettled API** - Interfaces for IO integration.
+ *
* @defgroup proactor Proactor
- * @brief **Experimental** - Multithreaded IO
+ * @brief **Unsettled API** - An API for multithreaded IO.
+ * @ingroup io
+ *
+ * @defgroup proactor_events Proactor events
+ * @brief **Unsettled API** - Events used by the proactor.
+ * @ingroup io
+ *
+ * @defgroup listener Listener
+ * @brief **Unsettled API** - A listener for incoming connections.
* @ingroup io
*
* @defgroup connection_driver Connection driver
- * @brief **Experimental** - Low-level IO integration
+ * @brief **Unsettled API** - An API for low-level IO integration.
+ * @ingroup io
*
* @defgroup messenger Messenger
* @deprecated
- * @brief **Deprecated** - The Messenger API
+ * @brief **Deprecated** - The Messenger API.
*
* @defgroup url URL
* @deprecated
- * @brief **Deprecated** - A URL parser
+ * @brief **Deprecated** - A URL parser.
*/
#ifdef __cplusplus
@@ -403,13 +415,14 @@ typedef struct pn_delivery_t pn_delivery_t;
typedef struct pn_collector_t pn_collector_t;
/**
- * A listener accepts connections.
+ * A listener for incoming connections.
+ *
* @ingroup listener
*/
typedef struct pn_listener_t pn_listener_t;
/**
- * An AMQP Transport object.
+ * A network channel supporting an AMQP connection.
*
* A pn_transport_t encapsulates the transport related state of all
* AMQP endpoint objects associated with a physical network connection
@@ -417,11 +430,12 @@ typedef struct pn_listener_t pn_listener_t;
*
* @ingroup transport
*/
-
typedef struct pn_transport_t pn_transport_t;
/**
- * The proactor, see pn_proactor()
+ * A harness for multithreaded IO.
+ *
+ * @ingroup proactor
*/
typedef struct pn_proactor_t pn_proactor_t;
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org
[2/2] qpid-proton git commit: PROTON-1543: Various copyedits and
additions to the C and C++ API docs
Posted by jr...@apache.org.
PROTON-1543: Various copyedits and additions to the C and C++ API docs
- Add a prominent note about deprecations
- Add file markup to all header files; add some deprecations
- Copyedit the work queue docs; hide void_function0
- Add a prominent note about unsettled APIs
- Bring the doxygen configs in sync; remove redundant nav
- Reorganize the C and C++ API topic-driven pages
- Copyedit the updated intro content
- Reconcile header file and module-level docs
- Minor consistency improvements
- Improve the container api docs
- Use 'Unsettled API' instead of 'Experimental'
- More consistent use of var names and placement of * and & qualifiers
- Remove default_container from the examples and the tutorial
Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo
Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/363d337b
Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/363d337b
Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/363d337b
Branch: refs/heads/master
Commit: 363d337b5cae8f1f68829ee06f4a89a07039ab3b
Parents: 7a5ded7
Author: Justin Ross <jr...@apache.org>
Authored: Mon Sep 11 05:46:32 2017 -0700
Committer: Justin Ross <jr...@apache.org>
Committed: Mon Sep 11 05:46:32 2017 -0700
----------------------------------------------------------------------
examples/cpp/tutorial.dox | 70 ++++---
proton-c/bindings/cpp/docs/headers.dox | 49 -----
proton-c/bindings/cpp/docs/io.md | 26 +--
proton-c/bindings/cpp/docs/main.md | 128 ++++---------
proton-c/bindings/cpp/docs/mt.md | 136 ++++++++-----
proton-c/bindings/cpp/docs/overview.md | 109 +++++++++++
proton-c/bindings/cpp/docs/types.md | 86 +++++++++
proton-c/bindings/cpp/docs/user.doxygen.in | 45 +++--
.../cpp/include/proton/annotation_key.hpp | 3 +
proton-c/bindings/cpp/include/proton/binary.hpp | 3 +
.../bindings/cpp/include/proton/byte_array.hpp | 3 +
.../cpp/include/proton/codec/common.hpp | 3 +
.../cpp/include/proton/codec/decoder.hpp | 5 +-
.../bindings/cpp/include/proton/codec/deque.hpp | 2 +-
.../cpp/include/proton/codec/encoder.hpp | 5 +-
.../cpp/include/proton/codec/forward_list.hpp | 2 +-
.../bindings/cpp/include/proton/codec/list.hpp | 2 +-
.../bindings/cpp/include/proton/codec/map.hpp | 2 +-
.../cpp/include/proton/codec/unordered_map.hpp | 2 +-
.../cpp/include/proton/codec/vector.hpp | 2 +-
.../bindings/cpp/include/proton/connection.hpp | 29 +--
.../cpp/include/proton/connection_options.hpp | 17 +-
.../bindings/cpp/include/proton/container.hpp | 190 +++++++++++--------
.../bindings/cpp/include/proton/decimal.hpp | 35 ++--
.../cpp/include/proton/default_container.hpp | 7 +-
.../bindings/cpp/include/proton/delivery.hpp | 3 +
.../cpp/include/proton/delivery_mode.hpp | 3 +
.../bindings/cpp/include/proton/duration.hpp | 13 +-
.../bindings/cpp/include/proton/endpoint.hpp | 3 +
proton-c/bindings/cpp/include/proton/error.hpp | 3 +
.../cpp/include/proton/error_condition.hpp | 3 +
.../bindings/cpp/include/proton/function.hpp | 13 +-
proton-c/bindings/cpp/include/proton/fwd.hpp | 3 +
.../cpp/include/proton/internal/data.hpp | 12 +-
.../cpp/include/proton/io/connection_driver.hpp | 9 +-
proton-c/bindings/cpp/include/proton/link.hpp | 3 +
.../cpp/include/proton/listen_handler.hpp | 3 +
.../bindings/cpp/include/proton/listener.hpp | 3 +
proton-c/bindings/cpp/include/proton/map.hpp | 3 +
.../bindings/cpp/include/proton/message.hpp | 35 ++--
.../bindings/cpp/include/proton/message_id.hpp | 3 +
.../cpp/include/proton/messaging_handler.hpp | 4 +-
.../bindings/cpp/include/proton/namespaces.hpp | 10 +-
.../bindings/cpp/include/proton/receiver.hpp | 3 +
.../cpp/include/proton/receiver_options.hpp | 3 +
.../cpp/include/proton/reconnect_options.hpp | 36 ++--
.../bindings/cpp/include/proton/returned.hpp | 20 +-
proton-c/bindings/cpp/include/proton/sasl.hpp | 3 +
proton-c/bindings/cpp/include/proton/scalar.hpp | 3 +
.../bindings/cpp/include/proton/scalar_base.hpp | 5 +-
proton-c/bindings/cpp/include/proton/sender.hpp | 3 +
.../cpp/include/proton/sender_options.hpp | 3 +
.../bindings/cpp/include/proton/session.hpp | 3 +
.../cpp/include/proton/session_options.hpp | 3 +
proton-c/bindings/cpp/include/proton/source.hpp | 3 +
.../cpp/include/proton/source_options.hpp | 3 +
proton-c/bindings/cpp/include/proton/ssl.hpp | 3 +
proton-c/bindings/cpp/include/proton/symbol.hpp | 5 +-
proton-c/bindings/cpp/include/proton/target.hpp | 3 +
.../cpp/include/proton/target_options.hpp | 3 +
.../bindings/cpp/include/proton/terminus.hpp | 3 +
.../bindings/cpp/include/proton/thread_safe.hpp | 4 +-
.../bindings/cpp/include/proton/timestamp.hpp | 13 +-
.../bindings/cpp/include/proton/tracker.hpp | 3 +
.../bindings/cpp/include/proton/transfer.hpp | 3 +
.../bindings/cpp/include/proton/transport.hpp | 3 +
.../bindings/cpp/include/proton/type_id.hpp | 5 +-
proton-c/bindings/cpp/include/proton/types.hpp | 90 +--------
.../bindings/cpp/include/proton/types_fwd.hpp | 2 +-
proton-c/bindings/cpp/include/proton/url.hpp | 7 +
proton-c/bindings/cpp/include/proton/uuid.hpp | 3 +
proton-c/bindings/cpp/include/proton/value.hpp | 3 +
.../bindings/cpp/include/proton/work_queue.hpp | 61 +++---
proton-c/docs/api/index.md | 36 ----
proton-c/docs/api/io.md | 16 ++
proton-c/docs/api/main.md | 33 ++++
proton-c/docs/api/user.doxygen.in | 8 +-
proton-c/include/proton/codec.h | 9 +-
proton-c/include/proton/condition.h | 2 +-
proton-c/include/proton/connection.h | 1 -
proton-c/include/proton/connection_driver.h | 34 ++--
proton-c/include/proton/disposition.h | 6 +-
proton-c/include/proton/event.h | 4 +-
proton-c/include/proton/link.h | 6 +-
proton-c/include/proton/listener.h | 20 +-
proton-c/include/proton/netaddr.h | 10 +-
proton-c/include/proton/proactor.h | 100 +++++-----
proton-c/include/proton/transport.h | 25 +--
proton-c/include/proton/types.h | 66 ++++---
89 files changed, 1018 insertions(+), 753 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/examples/cpp/tutorial.dox
----------------------------------------------------------------------
diff --git a/examples/cpp/tutorial.dox b/examples/cpp/tutorial.dox
index fbb419d..f49b9e3 100644
--- a/examples/cpp/tutorial.dox
+++ b/examples/cpp/tutorial.dox
@@ -6,11 +6,10 @@
/**
-@page tutorial Tutorial
+@page tutorial_page Tutorial
-This is a brief tutorial that will walk you through the fundamentals
-of building messaging applications in incremental steps. There are
-further examples, in addition the ones mentioned in the tutorial.
+This is a brief guide to to the fundamentals of building messaging
+applications using Qpid Proton C++.
Proton provides an "event-driven" programming model, where you
implement a subclass of `proton::messaging_handler` and override
@@ -18,13 +17,14 @@ functions that react to various AMQP events (connections opening and
closing, messages being delivered, and so on).
The examples below show how to implement handlers for clients and
-servers and how to run them using the `proton::container`, a
-portable, easy-to-use way to build single-threaded clients or servers.
+servers and how to run them using the `proton::container`, a portable,
+easy-to-use way to build single-threaded clients or servers.
-Some of the examples require an AMQP *broker* that can receive, store, and send
-messages. @ref broker.cpp define a simple example broker. If run without
-arguments, it listens on `0.0.0.0:5672`, the standard AMQP port on all network
-interfaces. To use a different port or network interface:
+Some of the examples require an AMQP *broker* that can receive, store,
+and send messages. @ref broker.cpp defines a simple example broker. If
+run without arguments, it listens on `0.0.0.0:5672`, the standard AMQP
+port on all network interfaces. To use a different port or network
+interface, use the `-a` option.
broker -a <host>:<port>
@@ -39,24 +39,22 @@ examples take an option `-a URL`. A URL looks like this:
It usually defaults to `127.0.0.1:5672/examples`, but you can change
this if your broker is on a different host or port, or you want to use
-a different queue or topic name (the ADDRESS part of the URL). URL
-details are at `proton::url`.
+a different queue or topic name (the ADDRESS part of the URL).
Hello World!
------------
\dontinclude helloworld.cpp
-Tradition dictates that we start with Hello World! This example
-demonstrates sending and receiving by sending a message to a broker
-and then receiving the same message back. In a realistic system the
-sender and receiver would normally be in different processes. The
-complete example is @ref helloworld.cpp
+Tradition dictates that we start with Hello World! This example sends
+a message to a broker and then receives the same message back. In a
+realistic system the sender and receiver would normally be in
+different processes. The complete example is @ref helloworld.cpp
-We will include the following classes: `proton::container` (an
-implementation of `proton::container`) runs an event loop which
-dispatches events to a `proton::messaging_handler`. This allows a
-*reactive* style of programming which is well suited to messaging
+We will include the following classes. `proton::container` runs an
+event loop which dispatches events to a
+`proton::messaging_handler`. This allows a *reactive* style of
+programming which is well suited to messaging
applications. `proton::connection` and `proton::delivery` are AMQP
entities used in the handler functions. `proton::url` is a simple
parser for the URL format mentioned above.
@@ -91,20 +89,20 @@ calls to `proton::messaging_handler::on_sendable()`.
`proton::messaging_handler::on_message()` is called when a message is
received. We just print the body of the message and close the
-connection, as we only want one message
+connection, as we only want one message.
\skip on_message
\until }
-The message body is a `proton::value`, see the documentation for more on how to
-extract the message body as type-safe C++ values.
+The message body is a `proton::value`. See @ref types_page for more
+on how to extract the message body as type-safe C++ values.
Our `main` function creates an instance of the `hello_world` handler
and a `proton::container` using that handler. Calling
`proton::container::run()` sets things in motion and returns when we
-close the connection as there is nothing further to do. It may throw
-an exception, which will be a subclass of `proton::error`. That in
-turn is a subclass of `std::exception`.
+close the connection. It may throw an exception, which will be a
+subclass of `proton::error`. That in turn is a subclass of
+`std::exception`.
\skip main
\until }
@@ -116,9 +114,9 @@ Hello World, direct!
\dontinclude helloworld_direct.cpp
-Though often used in conjunction with a broker, AMQP does not
-*require* this. It also allows senders and receivers to communicate
-directly if desired.
+Though often used in conjunction with a broker, AMQP does not require
+this. It also allows senders and receivers to communicate directly if
+desired.
We will modify our example to send a message directly to itself. This
is a bit contrived but illustrates both sides of the direct send and
@@ -131,9 +129,9 @@ invoking the `proton::container::listen()` method on the container.
\skip on_container_start
\until }
-As we only need then to initiate one link, the sender, we can do that
-by passing in a url rather than an existing connection, and the
-connection will also be automatically established for us.
+Since we only need to initiate one link, the sender, we can do that by
+passing in a URL rather than an existing connection. The connection
+will also be automatically established for us.
We send the message in response to the
`proton::messaging_handler::on_sendable()` callback and print the
@@ -155,7 +153,7 @@ the peer. We are notified of that event through the
Then, once the connection has been closed, of which we are notified
through the `proton::messaging_handler::on_connection_close()`
-callback, we stop accepting incoming connections. A that point there
+callback, we stop accepting incoming connections. At that point there
is no work to be done, the event loop exits, and the
`proton::container::run()` method returns.
@@ -164,8 +162,8 @@ is no work to be done, the event loop exits, and the
So now we have our example working without a broker involved!
-Note that for this example we pick an "unusual" port 8888 since we are talking
-to ourselves rather than a broker.
+Note that for this example we pick an "unusual" port 8888 since we are
+talking to ourselves rather than a broker.
\skipline url =
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/docs/headers.dox
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/docs/headers.dox b/proton-c/bindings/cpp/docs/headers.dox
deleted file mode 100644
index b85430b..0000000
--- a/proton-c/bindings/cpp/docs/headers.dox
+++ /dev/null
@@ -1,49 +0,0 @@
-/* List headers that lack their own @file marker so doxygen will link them properly.
- Ideally the files themselves should have their own @file markup and comment,
- if you update files that they can be removed from here.
- */
-/// @file proton/annotation_key.hpp Key type for proton::message annotation maps.
-/// @file proton/binary.hpp Binary data type
-/// @file proton/byte_array.hpp
-/// @file proton/connection.hpp AMQP connection
-/// @file proton/connection_options.hpp Options to create a proton::connection
-/// @file proton/container.hpp AMQP container to manage connections and listeners
-/// @file proton/decimal.hpp Placeholder for the AMQP decimal data type.
-/// @file proton/delivery.hpp Delivery state of an AQMP messsage
-/// @file proton/delivery_mode.hpp Delivery mode of an AMQP message
-/// @file proton/duration.hpp Time duration data type
-/// @file proton/error_condition.hpp AMQP error condition
-/// @file proton/error.hpp Base exception type thrown by proton functions
-/// @file proton/function.hpp
-/// @file proton/fwd.hpp
-/// @file proton/link.hpp
-/// @file proton/listener.hpp
-/// @file proton/listen_handler.hpp
-/// @file proton/map.hpp Template for AMQP property, annotation and filter maps.
-/// @file proton/message.hpp
-/// @file proton/message_id.hpp
-/// @file proton/messaging_handler.hpp
-/// @file proton/namespaces.hpp
-/// @file proton/receiver.hpp
-/// @file proton/receiver_options.hpp
-/// @file proton/sasl.hpp
-/// @file proton/scalar_base.hpp
-/// @file proton/scalar.hpp Run-time holder for any AMQP scalar value
-/// @file proton/sender.hpp
-/// @file proton/sender_options.hpp
-/// @file proton/session.hpp
-/// @file proton/session_options.hpp
-/// @file proton/source.hpp
-/// @file proton/source_options.hpp
-/// @file proton/ssl.hpp
-/// @file proton/symbol.hpp AMQP symbol (ASCII string) data type
-/// @file proton/target.hpp
-/// @file proton/target_options.hpp
-/// @file proton/terminus.hpp
-/// @file proton/timestamp.hpp
-/// @file proton/tracker.hpp
-/// @file proton/transfer.hpp
-/// @file proton/transport.hpp
-/// @file proton/url.hpp
-/// @file proton/uuid.hpp
-/// @file proton/value.hpp Run-time holder for any AMQP value
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 0734683..2bda1cf 100644
--- a/proton-c/bindings/cpp/docs/io.md
+++ b/proton-c/bindings/cpp/docs/io.md
@@ -3,18 +3,20 @@
**Unsettled API** - The `proton::io` interfaces are new and remain
subject to change.
-The `proton::io` namespace contains a service provider interface (SPI) that
-allows you to embed Proton in alternative IO or threading libraries.
+The `proton::io` namespace contains a service provider interface (SPI)
+that allows you to embed Proton in alternative IO or threading
+libraries.
-The `proton::io::connection_driver` class converts an AMQP-encoded byte stream,
-read from any IO source, into `proton::messaging_handler` calls. It generates an
-AMQP-encoded byte stream as output that can be written to any IO destination.
+The `proton::io::connection_driver` class converts an AMQP-encoded
+byte stream, read from any IO source, into `proton::messaging_handler`
+calls. It generates an AMQP-encoded byte stream as output that can be
+written to any IO destination.
-The connection driver has no threading or IO dependencies. It is not thread
-safe, but separate instances are independent and can be run concurrently in a
-multi-threaded framework. The driver is written in portable C++98-compatible
-code.
+The connection driver has no threading or IO dependencies. It is not
+thread-safe, but separate instances are independent and can be run
+concurrently in a multithreaded framework. The driver is written in
+portable C++98-compatible code.
-For examples of use you should look at
-[the proton source code](qpid.apache.org/proton), in particular the C++
-`proton::container`
+For examples of use, see
+[the proton source code](qpid.apache.org/proton), in particular the
+C++ `proton::container`.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/docs/main.md
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/docs/main.md b/proton-c/bindings/cpp/docs/main.md
index 8841287..63a357c 100644
--- a/proton-c/bindings/cpp/docs/main.md
+++ b/proton-c/bindings/cpp/docs/main.md
@@ -1,107 +1,47 @@
-
# Introduction {#mainpage}
-The [Qpid Proton](http://qpid.apache.org/proton) C++ library lets you write
-clients and servers that send and receive messages using the AMQP protocol, in
-C++. It can be used with single-threaded and multi-threaded code.
-
-The @ref tutorial will guide you through some basic example, there are
-further [examples](examples.html) on more advanced topics.
-
-## An overview of AMQP
-
-A proton::message has a *body* (the main content), application properties where
-you can store additional data, and specific properties defined by the AMQP
-protocol.
-
-Messages are transferred over *links*. The sending end of a link is a
-proton::sender, the receiving end is a proton::receiver. Links have a
-*source* and *target* address, as explained [below](#sources-and-targets)
-
-Links are grouped in a `proton::session`. Messages in the same session are sent
-sequentially, those on different sessions can be interleaved. A large message
-being sent on one session does not block messages being sent on other sessions.
-
-Sessions are on a `proton::connection`. If you don't need multiple sessions, a
-proton::connection will create links directly using a default session.
-
-A `proton::delivery` represents the delivery of a message, and allows the
-receiver to accept or reject it. The sender can use a `proton::tracker` to track
-the status of a sent message and find out if it was accepted.
-
-A delivery is *settled* when both ends are done with it. Different settlement
-methods give different levels of reliability: *at-most-once*, *at-least-once*,
-and *exactly-once*. See [below](#delivery-guarantees)
-
-## Anatomy of a Proton application
-
-proton::container is the top-level object in a proton application.
-A client uses proton::container::connect() to establish connections, a server
-uses proton::container::listen() to accept connections.de
-
-Proton is an event-driven API. You implement a subclass of
-`proton::messaging_handler` and over-ride functions to handle AMQP events, such
-as `on_container_open()` or `on_message()`. Each proton::connection is
-associated with a handler for its events. proton::container::run() polls all
-connections and listeners and dispatches events to your handlers.
-
-A message body can be a string or byte-sequence encoded in any way you
-like. However AMQP also provides standard, inter-operable encodings for basic
-data types and structures like maps and lists. You can use this encoding for
-your message bodies via `proton::value` and `proton::scalar`, which convert C++
-types to their AMQP equivalent.
-
-The @ref tutorial will guide you through some basic example, there are
-further [examples](examples.html) on more advanced topics.
-
-## Sources and targets
+The Qpid Proton C++ API enables writing clients and servers that send
+and receive messages using the AMQP protocol. It is part of the
+[Qpid Proton](https://qpid.apache.org/proton/index.html) suite of
+messaging APIs.
-Every link has two addresses, *source* and *target*. The most common pattern for
-using these addresses is as follows:
+The @ref overview_page presents the API's central concepts and
+mechanics.
-When a client creates a *receiver* link, it sets the *source* address. This
-means "I want to receive messages from this source." This is often referred to
-as "subscribing" to the source. When a client creates a *sender* link, it sets
-the *target* address. This means "I want to send to this target."
+The @ref tutorial_page guides you through some basic examples. See
+[**Examples**](examples.html) for a complete list of the sample
+programs, including more advanced ones.
-In the case of a broker, the source or target usually refers to a queue or
-topic. In general they can refer to any AMQP-capable node.
+Qpid Proton C++ can be used in single- and multithreaded applications.
+See @ref mt_page for guidance on writing efficient multithreaded
+messaging applications.
-In the *request-response* pattern, a request message carries a *reply-to*
-address for the response message. This can be any AMQP address, but it is often
-useful to create a temporary address for the response message. The client
-creates a *receiver* with no source address and the *dynamic* flag set. The
-server generates a unique *source* address for the receiver, which is discarded
-it when the link closes. The client uses this source address as the reply-to
-when it sends the request, so the response is delivered to the client's
-receiver.
+## Namespaces
-The @ref server_direct.cpp example shows how to implement a request-response
-server.
+The main @ref proton namespace contains classes and functions
+representing AMQP concepts and key elements of the API. Together they
+form a "protocol engine" API to create AMQP @ref proton::connection
+"connections" and @ref proton::link "links", handle @ref
+proton::messaging\_handler "events", and send and receive @ref
+proton::message "messages". See @ref overview_page for more
+information.
-## Delivery guarantees
+The main @ref proton namespace also contains C++ classes and functions
+for handling AMQP- and API-specific data types. See @ref types_page
+for more information.
-Proton offers three levels of message delivery guarantee:
-*at-most-once*, *at-least-once*, and *exactly-once*.
+The @ref proton::codec namespace contains interfaces for AMQP data
+encoding and decoding.
-For *at-most-once*, the sender settles the message as soon as it sends
-it. If the connection is lost before the message is received by the
-receiver, the message will not be delivered.
+The @ref proton::io namespace contains interfaces for integrating with
+platform-native network IO. See @ref io_page for more information.
-For *at-least-once*, the receiver accepts and settles the message on
-receipt. If the connection is lost before the sender is informed of
-the settlement, then the delivery is considered in-doubt and should be
-retried. This will ensure it eventually gets delivered (provided of
-course the connection and link can be reestablished). It may mean that
-it is delivered multiple times, however.
+## Conventions
-Finally, for *exactly-once*, the receiver accepts the message but
-doesn't settle it. The sender settles once it is aware that the
-receiver accepted it. In this way the receiver retains knowledge of an
-accepted message until it is sure the sender knows it has been
-accepted. If the connection is lost before settlement, the receiver
-informs the sender of all the unsettled deliveries it knows about, and
-from this the sender can deduce which need to be redelivered. The
-sender likewise informs the receiver which deliveries it knows about,
-from which the receiver can deduce which have already been settled.
+Elements of the API marked as **Unsettled API**, including any
+elements contained within them, are still evolving and thus are
+subject to change. They are available to use, but newer versions of
+Proton may require changes to your application source code.
+Elements marked **Deprecated** are slated for removal in a future
+release.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/docs/mt.md
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/docs/mt.md b/proton-c/bindings/cpp/docs/mt.md
index 8e54f5c..5b60278 100644
--- a/proton-c/bindings/cpp/docs/mt.md
+++ b/proton-c/bindings/cpp/docs/mt.md
@@ -1,81 +1,113 @@
-# Multi-threading {#mt_page}
+# Multithreading {#mt_page}
-Full multi-threading support is available with C++11 and later. Limited
-multi-threading is possible with older versions of C++, see the final section of
-this page.
+Full multithreading support is available with C++11 and later. Limited
+multithreading is possible with older versions of C++. See the last
+section of this page for more information.
-`proton::message` is a value type with the same threading constraints as a
-standard C++ built-in type, it cannot be concurrently modified.
+## Thread-safety rules
-The `proton::container` is thread safe *with C++11 or greater*. It provides the following:
+`proton::message` is a value type with the same threading constraints
+as a standard C++ built-in type. It cannot be concurrently modified.
-* User threads can open (or listen for) new connections at any time.
-* Manages worker threads to process connections.
-* Handles network IO and calls the relevant `proton::messaging_handler::on_xxx` event callbacks that can be over-ridden by user code.
+The `proton::container` is thread-safe *with C++11 or greater*. It has
+the following capabilities.
-The `proton::container` ensures that calls to event callbacks for each connection
-instance are *serialized* (not called concurrently), but callbacks for different
-connections may be called in parallel.
+ * Application threads can open (or listen for) new connections at any
+ time.
-@note The `proton::connection` and related objects (`proton::session`,
-`proton::sender`, `proton::receiver`, `proton::delivery`) are *not* thread safe, and
-are subject to the following rules:
+ * It manages worker threads to process connections.
-1. They may only be used from a `proton::messaging_handler` event callback called by proton (or a `proton::work_queue` function, more below)
+ * It handles network IO and calls the relevant
+ `proton::messaging_handler` event callbacks to execute application
+ code.
-2. You can't use objects belonging to one connection in a callback for a different connection. We recommend a single handler instance per connection to avoid confusion.
+The `proton::container` ensures that calls to event callbacks for each
+connection instance are *serialized* (not called concurrently), but
+callbacks for different connections can be safely executed in
+parallel.
-3. You can store proton objects in member variables for use in a later callback, provided you respect 2.
+The `proton::connection` and related objects (`proton::session`,
+`proton::sender`, `proton::receiver`, `proton::delivery`) are *not*
+thread-safe and are subject to the following rules.
-The `proton::work_queue` provides a safe way to communicate between different
-connection handlers or between non-proton threads and connection handlers.
+1. They can only be used from a `proton::messaging_handler` event
+ callback called by Proton or a `proton::work_queue` function (more
+ below).
-* Each connection has an associated `proton::work_queue`
-* The work queue is thread safe (C++11 or greater), any thread can add work.
-* "work" is a `std::function` and bound arguments to be called like an event callback.
+2. You cannot use objects belonging to one connection from a callback
+ for another connection. We recommend a single handler instance per
+ connection to avoid confusion.
-When the work function is called by proton, it will be serialized safely so that
-you can treat the work function like an event callback and safely access the
-handler and proton objects stored on it.
+3. You can store Proton objects in member variables for use in a later
+ callback, provided you respect rule two.
-The examples @ref multithreaded_client.cpp and @ref multithreaded_client_flow_control.cpp show
-how you can send/receive messages from non-proton threads using these techniques.
+## Work queues
+`proton::work_queue` provides a safe way to communicate between
+different connection handlers or between non-Proton threads and
+connection handlers.
+
+ * Each connection has an associated `proton::work_queue`.
+
+ * The work queue is thread-safe (C++11 or greater). Any thread can
+ add *work*.
+
+ * *Work* is a `std::function`, and bound arguments will be
+ called like an event callback.
+
+When the work function is called by Proton, it will be serialized
+safely so that you can treat the work function like an event callback
+and safely access the handler and Proton objects stored on it.
+
+The examples @ref multithreaded_client.cpp and @ref
+multithreaded_client_flow_control.cpp show how you can send and
+receive messages from non-Proton threads using work queues.
## The wake primitive
-`proton::connection::wake()` allows any thread to "wake up" a connection by
-generating a `proton::messaging_handler::on_connection_wake()` callback. This is
+`proton::connection::wake()` allows any thread to "wake up" a
+connection by generating an `on_connection_wake()` callback. This is
the *only* thread-safe `proton::connection` function.
-This is a light-weight, low-level primitive for signalling between threads:
+This is a lightweight, low-level primitive for signaling between
+threads.
+
+ * It does not carry any code or data (unlike `proton::work_queue`).
+
+ * Multiple calls to `wake()` can be "coalesced" into a single
+ `on_connection_wake()`.
-* It does not carry any code or data (unlike `proton::work_queue`)
-* Multiple calls to wake() can be "coalesced" into a single `proton::messaging_handler::on_connection_wake()`
-* There may be calls to `proton::messaging_handler::on_connection_wake()` occur without any call to `connection::wake()`, generated internally by the library.
+ * Calls to `on_connection_wake()` can occur without any call to
+ `connection::wake()`. Proton uses wake internally.
-The semantics of `wake()` are similar to `std::condition_variable::notify_one`:
-there will be a wakeup, but there must be some shared application state to
-determine why the wakeup occurred and what, if anything, to do about it.
+The semantics of `wake()` are similar to
+`std::condition_variable::notify_one`. There will be a wakeup, but
+there must be some shared application state to determine why the
+wakeup occurred and what, if anything, to do about it.
-`proton::work_queue` is easier to use in many instances, but `wake()` may be
-useful if you already have your own external thread-safe queues and just need an
-efficient way to wake a connection to check them for data.
+Work queues are easier to use in many instances, but `wake()` may be
+useful if you already have your own external thread-safe queues and
+just need an efficient way to wake a connection to check them for
+data.
## Using older versions of C++
-Before C++11 there was no standard support for threading in C++. You can use
-proton with threads but with limitations:
+Before C++11 there was no standard support for threading in C++. You
+can use Proton with threads but with the following limitations.
-* The container will not create threads, it will only use the single thread that calls proton::container::run()
+ * The container will not create threads, it will only use the single
+ thread that calls `proton::container::run()`.
-* None of the proton library classes are thread-safe, including proton::container and proton::work_queue. You need an external lock to use proton::container in multiple threads.
+ * None of the Proton library classes are thread-safe, including
+ `proton::container` and `proton::work_queue`. You need an external
+ lock to use `proton::container` in multiple threads.
-The only exception is `proton::connection::wake()`, it *is* thread safe even in older C++.
+The only exception is `proton::connection::wake()`, it *is*
+thread-safe even in older C++.
-You can implement your own `proton::container` using your own threading library,
-or ignore the container and embed the lower-level `proton::connection_engine` in
-an external poller. These approaches still use the same
-`proton::messaging_handler` callbacks, so you can re-use most of your
-application code. This is an advanced undertaking, there are a few pointers on
-@ref io_page.
+You can implement your own `proton::container` using your own
+threading library, or ignore the container and embed the lower-level
+`proton::io::connection_driver` in an external poller. These
+approaches still use the same `proton::messaging_handler` callbacks,
+so you can reuse most of your application code. Note that this is an
+advanced undertaking. There are a few pointers in @ref io_page.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/docs/overview.md
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/docs/overview.md b/proton-c/bindings/cpp/docs/overview.md
new file mode 100644
index 0000000..7a299b8
--- /dev/null
+++ b/proton-c/bindings/cpp/docs/overview.md
@@ -0,0 +1,109 @@
+# Overview {#overview_page}
+
+Qpid Proton's concepts and capabilities closely match those of its
+wire protocol, AMQP. See
+[the Qpid AMQP page](https://qpid.apache.org/amqp/index.html) and
+[the AMQP 1.0 spec](http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-overview-v1.0-os.html)
+for more information.
+
+## Key concepts
+
+A `proton::message` has a *body* (the main content), application
+properties where you can store additional data, and specific
+properties defined by AMQP.
+
+Messages are transferred over *links*. The sending end of a link is a
+`proton::sender`, and the receiving end is a `proton::receiver`.
+Links have a *source* and *target* address, as explained
+[below](#sources-and-targets).
+
+Links are grouped in a `proton::session`. Messages in the same session
+are sent sequentially, while those on different sessions can be
+interleaved. A large message being sent on one session does not block
+messages being sent on another session.
+
+Sessions belong to a `proton::connection`. If you don't need multiple
+sessions, a connection will create links directly using a default
+session.
+
+A `proton::delivery` represents the transfer of a message and allows
+the receiver to accept or reject it. The sender can use a
+`proton::tracker` to track the status of a sent message and find out
+if it was accepted.
+
+A delivery is *settled* when both ends are done with it. Different
+settlement methods give different levels of reliability:
+*at-most-once*, *at-least-once*, and *exactly-once*. See
+[below](#delivery-guarantees).
+
+## The anatomy of a Proton application
+
+`proton::container` is the top-level object in a Proton application.
+A client uses `proton::container::connect()` to establish connections.
+A server uses `proton::container::listen()` to accept connections.
+
+Proton is an event-driven API. You implement a subclass of
+`proton::messaging_handler` and override functions to handle AMQP
+events, such as `on_container_open()` or `on_message()`. Each
+connection is associated with a handler for its events.
+`proton::container::run()` polls all connections and listeners and
+dispatches events to your handlers.
+
+A message body can be a string or byte sequence encoded any way you
+like. However, AMQP also provides standard, interoperable encodings
+for basic data types and structures such as maps and lists. You can
+use this encoding for your message bodies via `proton::value` and
+`proton::scalar`, which convert C++ types to their AMQP equivalents.
+
+## Sources and targets
+
+Every link has two addresses, *source* and *target*. The most common
+pattern for using these addresses is as follows.
+
+When a client creates a *receiver* link, it sets the *source*
+address. This means "I want to receive messages from this
+source". This is often referred to as "subscribing" to the
+source. When a client creates a *sender* link, it sets the *target*
+address. This means "I want to send to this target".
+
+In the case of a broker, the source or target usually refers to a
+queue or topic. In general they can refer to any AMQP-capable node.
+
+In the *request-response* pattern, a request message carries a
+*reply-to* address for the response message. This can be any AMQP
+address, but it is often useful to create a temporary address for the
+response message. The client creates a *receiver* with no source
+address and the *dynamic* flag set. The server generates a unique
+*source* address for the receiver, which is discarded when the link
+closes. The client uses this source address as the reply-to when it
+sends the request, so the response is delivered to the client's
+receiver.
+
+The @ref server_direct.cpp example shows how to implement a
+request-response server.
+
+## Delivery guarantees
+
+Proton offers three levels of message delivery guarantee:
+*at-most-once*, *at-least-once*, and *exactly-once*.
+
+For *at-most-once*, the sender settles the message as soon as it sends
+it. If the connection is lost before the message is received by the
+receiver, the message will not be delivered.
+
+For *at-least-once*, the receiver accepts and settles the message on
+receipt. If the connection is lost before the sender is informed of
+the settlement, then the delivery is considered in-doubt and should be
+retried. This will ensure it eventually gets delivered (provided of
+course the connection and link can be reestablished). It may mean that
+it is delivered multiple times, however.
+
+Finally, for *exactly-once*, the receiver accepts the message but
+doesn't settle it. The sender settles once it is aware that the
+receiver accepted it. In this way the receiver retains knowledge of an
+accepted message until it is sure the sender knows it has been
+accepted. If the connection is lost before settlement, the receiver
+informs the sender of all the unsettled deliveries it knows about, and
+from this the sender can deduce which need to be redelivered. The
+sender likewise informs the receiver which deliveries it knows about,
+from which the receiver can deduce which have already been settled.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/docs/types.md
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/docs/types.md b/proton-c/bindings/cpp/docs/types.md
new file mode 100644
index 0000000..6c24d47
--- /dev/null
+++ b/proton-c/bindings/cpp/docs/types.md
@@ -0,0 +1,86 @@
+# AMQP and C++ types {#types_page}
+
+An AMQP message body can hold binary data using any encoding you
+like. AMQP also defines its own encoding and types. The AMQP encoding
+is often used in message bodies because it is supported by AMQP
+libraries on many languages and platforms. You also need to use the
+AMQP types to set and examine message properties.
+
+## Scalar types
+
+Each type is identified by a proton::type_id.
+
+C++ type | AMQP type_id | Description
+--------------------|----------------------|-----------------------
+bool | proton::BOOLEAN | Boolean true or false
+uint8_t | proton::UBYTE | 8-bit unsigned byte
+int8_t | proton::BYTE | 8-bit signed byte
+uint16_t | proton::USHORT | 16-bit unsigned integer
+int16_t | proton::SHORT | 16-bit signed integer
+uint32_t | proton::UINT | 32-bit unsigned integer
+int32_t | proton::INT | 32-bit signed integer
+uint64_t | proton::ULONG | 64-bit unsigned integer
+int64_t | proton::LONG | 64-bit signed integer
+wchar_t | proton::CHAR | 32-bit unicode code point
+float | proton::FLOAT | 32-bit binary floating point
+double | proton::DOUBLE | 64-bit binary floating point
+proton::timestamp | proton::TIMESTAMP | 64-bit signed milliseconds since 00:00:00 (UTC), 1 January 1970.
+proton::decimal32 | proton::DECIMAL32 | 32-bit decimal floating point
+proton::decimal64 | proton::DECIMAL64 | 64-bit decimal floating point
+proton::decimal128 | proton::DECIMAL128 | 128-bit decimal floating point
+proton::uuid | proton::UUID | 128-bit universally-unique identifier
+std::string | proton::STRING | UTF-8 encoded Unicode string
+proton::symbol | proton::SYMBOL | 7-bit ASCII encoded string
+proton::binary | proton::BINARY | Variable-length binary data
+
+## Holder types
+
+`proton::message::body()` and other message-related data can contain
+different types of data at runtime. There are two "holder" types
+provided to hold runtime typed data:
+
+ - `proton::scalar` can hold a scalar value of any type.
+ - `proton::value` can hold any AMQP value, scalar or compound.
+
+You can set the value in a holder by assignment, and use the
+`proton::get()` and `proton::coerce()` templates to extract data in a
+type-safe way. Holders also provide functions to query the type of
+value they contain.
+
+## Compound types
+
+C++ type | AMQP type_id | Description
+--------------------|----------------------|-----------------------
+See below | proton::ARRAY | Sequence of values of the same type
+See below | proton::LIST | Sequence of values of mixed types
+See below | proton::MAP | Map of key-value pairs
+
+A `proton::value` containing a `proton::ARRAY` can convert to and from
+C++ sequences of the corresponding C++ type: `std::vector`,
+`std::deque`, `std::list`, and `std::forward_list`.
+
+`proton::LIST` converts to and from sequences of `proton::value` or
+`proton::scalar`, which can hold mixed types of data.
+
+`proton::MAP` converts to and from `std::map`, `std::unordered_map`,
+and sequences of `std::pair`.
+
+For example, you can decode a message body with any AMQP map as
+follows.
+
+ proton::message m = ...;
+ std::map<proton::value, proton::value> map;
+ proton::get(m.body(), map);
+
+You can encode a message body with a map of string keys and `uint64_t`
+values like this:
+
+ std::unordered_map<std::string, uint64_t> map;
+ map["foo"] = 123;
+ m.body() = map;
+
+## Include files
+
+`proton/types.hpp` includes all available type definitions and
+conversions. Alternatively, you can selectively include the `.hpp`
+files you want.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/docs/user.doxygen.in
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/docs/user.doxygen.in b/proton-c/bindings/cpp/docs/user.doxygen.in
index a56eb98..e971b19 100644
--- a/proton-c/bindings/cpp/docs/user.doxygen.in
+++ b/proton-c/bindings/cpp/docs/user.doxygen.in
@@ -37,42 +37,47 @@ HIDE_COMPOUND_REFERENCE = YES
HIDE_SCOPE_NAMES = YES
MAX_INITIALIZER_LINES = 0
ALPHABETICAL_INDEX = NO
+SORT_MEMBER_DOCS = NO
# Redefine protected as private and strip out the PN_CPP_EXTERN macro
-ENABLE_PREPROCESSING = YES
-MACRO_EXPANSION = YES
-EXPAND_ONLY_PREDEF = YES
-PREDEFINED = protected=private PN_CPP_EXTERN= PN_CPP_OVERRIDE= PN_CPP_HAS_CPP11=1 PN_CPP_HAS_SHARED_PTR=1 PN_CPP_HAS_UNIQUE_PTR=1 PN_CPP_HAS_LONG_LONG=1 PN_CPP_HAS_NULLPTR=1 PN_CPP_HAS_RVALUE_REFERENCES=1 PN_CPP_HAS_OVERRIDE=override PN_CPP_HAS_EXPLICIT_CONVERSIONS=1 PN_CPP_HAS_DEFAULTED_FUNCTIONS=1 PN_CPP_HAS_DELETED_FUNCTIONS=1 PN_CPP_HAS_STD_FUNCTION=1 PN_CPP_HAS_CHRONO=1
-EXCLUDE_SYMBOLS = internal internal::*
+ENABLE_PREPROCESSING = YES
+MACRO_EXPANSION = YES
+EXPAND_ONLY_PREDEF = YES
+PREDEFINED = protected=private PN_CPP_EXTERN= PN_CPP_OVERRIDE= PN_CPP_HAS_CPP11=1 PN_CPP_HAS_SHARED_PTR=1 PN_CPP_HAS_UNIQUE_PTR=1 PN_CPP_HAS_LONG_LONG=1 PN_CPP_HAS_NULLPTR=1 PN_CPP_HAS_RVALUE_REFERENCES=1 PN_CPP_HAS_OVERRIDE=override PN_CPP_HAS_EXPLICIT_CONVERSIONS=1 PN_CPP_HAS_DEFAULTED_FUNCTIONS=1 PN_CPP_HAS_DELETED_FUNCTIONS=1 PN_CPP_HAS_STD_FUNCTION=1 PN_CPP_HAS_CHRONO=1
+EXCLUDE_SYMBOLS = internal internal::*
# Configuration options related to warning and progress messages
-QUIET = YES
-WARNINGS = YES
+QUIET = YES
+WARNINGS = YES
# Configuration options related to the input files
-INPUT = @CMAKE_SOURCE_DIR@/proton-c/bindings/cpp/include @CMAKE_SOURCE_DIR@/proton-c/bindings/cpp/docs @CMAKE_SOURCE_DIR@/examples/cpp
-FILE_PATTERNS = *.hpp *.md *.dox
-EXCLUDE_PATTERNS = @CMAKE_SOURCE_DIR@/examples/*.?pp # Don't parse example sources, only *.dox
-FULL_PATH_NAMES = YES
-RECURSIVE = YES
-STRIP_FROM_PATH = @CMAKE_SOURCE_DIR@/proton-c/bindings/cpp/include
-EXAMPLE_PATH = @CMAKE_SOURCE_DIR@/examples/cpp
-EXAMPLE_RECURSIVE = YES
+INPUT = @CMAKE_SOURCE_DIR@/proton-c/bindings/cpp/include \
+ @CMAKE_SOURCE_DIR@/proton-c/bindings/cpp/docs \
+ @CMAKE_SOURCE_DIR@/examples/cpp
+FILE_PATTERNS = *.hpp *.md *.dox
+EXCLUDE_PATTERNS = @CMAKE_SOURCE_DIR@/examples/*.?pp \
+ @CMAKE_SOURCE_DIR@/proton-c/bindings/cpp/include/proton/internal/*.hpp
+FULL_PATH_NAMES = YES
+RECURSIVE = YES
+STRIP_FROM_PATH = @CMAKE_SOURCE_DIR@/proton-c/bindings/cpp/include
+EXAMPLE_PATH = @CMAKE_SOURCE_DIR@/examples/cpp
+EXAMPLE_RECURSIVE = YES
# View and list options
+DISABLE_INDEX = YES
GENERATE_TREEVIEW = YES
GENERATE_TODOLIST = NO
GENERATE_TESTLIST = NO
GENERATE_BUGLIST = NO
-GENERATE_DEPRECATEDLIST = YES
+GENERATE_DEPRECATEDLIST = NO
# Configuration options related to the output format
-GENERATE_HTML = YES
-HTML_OUTPUT = html
-HTML_FILE_EXTENSION = .html
-GENERATE_LATEX = NO
+GENERATE_HTML = YES
+HTML_OUTPUT = html
+HTML_FILE_EXTENSION = .html
+GENERATE_LATEX = NO
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/annotation_key.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/annotation_key.hpp b/proton-c/bindings/cpp/include/proton/annotation_key.hpp
index 02f5420..f9cc129 100644
--- a/proton-c/bindings/cpp/include/proton/annotation_key.hpp
+++ b/proton-c/bindings/cpp/include/proton/annotation_key.hpp
@@ -27,6 +27,9 @@
#include <proton/type_compat.h>
+/// @file
+/// @copybrief proton::annotation_key
+
namespace proton {
/// A key for use with AMQP annotation maps.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/binary.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/binary.hpp b/proton-c/bindings/cpp/include/proton/binary.hpp
index cf4c7a2..e2a8ebc 100644
--- a/proton-c/bindings/cpp/include/proton/binary.hpp
+++ b/proton-c/bindings/cpp/include/proton/binary.hpp
@@ -31,6 +31,9 @@
#include <string>
#include <vector>
+/// @file
+/// @copybrief proton::binary
+
namespace proton {
/// Arbitrary binary data.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/byte_array.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/byte_array.hpp b/proton-c/bindings/cpp/include/proton/byte_array.hpp
index 9040133..2f32b3b 100644
--- a/proton-c/bindings/cpp/include/proton/byte_array.hpp
+++ b/proton-c/bindings/cpp/include/proton/byte_array.hpp
@@ -29,6 +29,9 @@
#include <algorithm>
#include <iterator>
+/// @file
+/// @copybrief proton::byte_array
+
namespace proton {
namespace internal {
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 61de8a5..7bd1e5c 100644
--- a/proton-c/bindings/cpp/include/proton/codec/common.hpp
+++ b/proton-c/bindings/cpp/include/proton/codec/common.hpp
@@ -24,6 +24,9 @@
#include "../type_id.hpp"
+/// @file
+/// **Unsettled API** - Shared codec functions.
+
namespace proton {
namespace codec {
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 cf42f90..5f587ff 100644
--- a/proton-c/bindings/cpp/include/proton/codec/decoder.hpp
+++ b/proton-c/bindings/cpp/include/proton/codec/decoder.hpp
@@ -31,6 +31,9 @@
#include <utility>
+/// @file
+/// @copybrief proton::codec::decoder
+
namespace proton {
class annotation_key;
@@ -44,7 +47,7 @@ class value_base;
namespace codec {
-/// **Unsettled API** - Stream-like decoder from AMQP bytes to C++
+/// **Unsettled API** - A stream-like decoder from AMQP bytes to C++
/// values.
///
/// For internal use only.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/codec/deque.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/codec/deque.hpp b/proton-c/bindings/cpp/include/proton/codec/deque.hpp
index 188da2a..bdac2e7 100644
--- a/proton-c/bindings/cpp/include/proton/codec/deque.hpp
+++ b/proton-c/bindings/cpp/include/proton/codec/deque.hpp
@@ -21,7 +21,7 @@
*/
/// @file
-/// Enable conversions between proton::value and std::deque
+/// **Unsettled API** - Enable conversions between `proton::value` and `std::deque`.
#include "./encoder.hpp"
#include "./decoder.hpp"
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 043e999..f2c0336 100644
--- a/proton-c/bindings/cpp/include/proton/codec/encoder.hpp
+++ b/proton-c/bindings/cpp/include/proton/codec/encoder.hpp
@@ -29,6 +29,9 @@
#include <proton/type_compat.h>
+/// @file
+/// @copybrief proton::codec::encoder
+
namespace proton {
class scalar_base;
@@ -38,7 +41,7 @@ class value_base;
namespace codec {
-/// **Unsettled API** - Stream-like encoder from C++ values to AMQP
+/// **Unsettled API** - A stream-like encoder from C++ values to AMQP
/// bytes.
///
/// For internal use only.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/codec/forward_list.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/codec/forward_list.hpp b/proton-c/bindings/cpp/include/proton/codec/forward_list.hpp
index 4f09f3e..a7e46e1 100644
--- a/proton-c/bindings/cpp/include/proton/codec/forward_list.hpp
+++ b/proton-c/bindings/cpp/include/proton/codec/forward_list.hpp
@@ -21,7 +21,7 @@
*/
/// @file
-/// Enable conversions between proton::value and std::forward_list
+/// **Unsettled API** - Enable conversions between `proton::value` and `std::forward_list`.
#include "./encoder.hpp"
#include "./decoder.hpp"
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/codec/list.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/codec/list.hpp b/proton-c/bindings/cpp/include/proton/codec/list.hpp
index e914a5b..7c96f45 100644
--- a/proton-c/bindings/cpp/include/proton/codec/list.hpp
+++ b/proton-c/bindings/cpp/include/proton/codec/list.hpp
@@ -23,7 +23,7 @@
*/
/// @file
-/// Enable conversions between proton::value and std::list
+/// **Unsettled API** - Enable conversions between `proton::value` and `std::list`.
#include "./encoder.hpp"
#include "./decoder.hpp"
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/codec/map.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/codec/map.hpp b/proton-c/bindings/cpp/include/proton/codec/map.hpp
index 45f9df9..9f17b98 100644
--- a/proton-c/bindings/cpp/include/proton/codec/map.hpp
+++ b/proton-c/bindings/cpp/include/proton/codec/map.hpp
@@ -23,7 +23,7 @@
*/
/// @file
-/// Enable conversions between proton::value and std::map
+/// **Unsettled API** - Enable conversions between `proton::value` and `std::map`.
#include "./encoder.hpp"
#include "./decoder.hpp"
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/codec/unordered_map.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/codec/unordered_map.hpp b/proton-c/bindings/cpp/include/proton/codec/unordered_map.hpp
index d26ec29..57a3b87 100644
--- a/proton-c/bindings/cpp/include/proton/codec/unordered_map.hpp
+++ b/proton-c/bindings/cpp/include/proton/codec/unordered_map.hpp
@@ -23,7 +23,7 @@
*/
/// @file
-/// Enable conversions between proton::value and std::unordered_map
+/// **Unsettled API** - Enable conversions between `proton::value` and `std::unordered_map`.
#include "./encoder.hpp"
#include "./decoder.hpp"
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/codec/vector.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/codec/vector.hpp b/proton-c/bindings/cpp/include/proton/codec/vector.hpp
index 8674f56..4dee919 100644
--- a/proton-c/bindings/cpp/include/proton/codec/vector.hpp
+++ b/proton-c/bindings/cpp/include/proton/codec/vector.hpp
@@ -23,7 +23,7 @@
*/
/// @file
-/// Enable conversions between proton::value and std::vector
+/// **Unsettled API** - Enable conversions between `proton::value` and `std::vector`.
#include "./encoder.hpp"
#include "./decoder.hpp"
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/connection.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/connection.hpp b/proton-c/bindings/cpp/include/proton/connection.hpp
index cac403b..cc372be 100644
--- a/proton-c/bindings/cpp/include/proton/connection.hpp
+++ b/proton-c/bindings/cpp/include/proton/connection.hpp
@@ -32,6 +32,9 @@
#include <string>
+/// @file
+/// @copybrief proton::connection
+
struct pn_connection_t;
namespace proton {
@@ -140,22 +143,24 @@ PN_CPP_CLASS_EXTERN connection : public internal::object<pn_connection_t>, publi
/// @see @ref connection_options::idle_timeout
PN_CPP_EXTERN uint32_t idle_timeout() const;
- /// **Unsettled API** - trigger an event from another thread
+ /// **Unsettled API** - Trigger an event from another thread.
///
- /// wake() can be called from any thread. The proton library will call
- /// messaging_handler::on_connection_wake() as soon as possible in the correct
- /// event handling thread.
+ /// `wake()` can be called from any thread. The Proton library
+ /// will call `messaging_handler::on_connection_wake()` as soon as
+ /// possible in the correct event-handling thread.
///
/// @note
- /// * Thread safe: this is the *only* @ref connection function that can be
- /// called from outside the handler thread.
- /// * Multiple calls to wake() may be coalesced into a single call to
- /// messaging_handler::on_connection_wake() that occurs after all of them.
- /// * Spurious messaging_handler::on_connection_wake() calls can occur even if the application
- /// does not call wake()
///
- /// @see work_queue provides an easier way execute code safely in the
- /// event handler thread.
+ /// * Thread-safe: This is the *only* @ref connection function
+ /// that can be called from outside the handler thread.
+ /// * Multiple calls to `wake()` may be coalesced into a single
+ /// call to `messaging_handler::on_connection_wake()` that
+ /// occurs after all of them.
+ /// * Spurious `messaging_handler::on_connection_wake()` calls can
+ /// occur even if the application does not call `wake()`.
+ ///
+ /// The @ref work_queue interface provides an easier way execute
+ /// code safely in the event-handler thread.
PN_CPP_EXTERN void wake() const;
/// @cond INTERNAL
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 02a9027..54268e0 100644
--- a/proton-c/bindings/cpp/include/proton/connection_options.hpp
+++ b/proton-c/bindings/cpp/include/proton/connection_options.hpp
@@ -34,6 +34,9 @@
#include <vector>
#include <string>
+/// @file
+/// @copybrief proton::connection_options
+
struct pn_connection_t;
namespace proton {
@@ -64,7 +67,7 @@ class connection_options {
/// Create an empty set of options.
PN_CPP_EXTERN connection_options();
- /// Shorthand for connection_options().handler(h)
+ /// Shorthand for `connection_options().handler(h)`.
PN_CPP_EXTERN connection_options(class messaging_handler& h);
/// Copy options.
@@ -112,15 +115,16 @@ class connection_options {
/// unset by default.
///
/// This value overrides any user name that is specified in the
- /// URL used for container::connect. It is ignored if the
- /// connection is created by container::listen because a listening
- /// connection's identity is provided by the remote client.
+ /// URL used for `container::connect`. It is ignored if the
+ /// connection is created by `container::listen` because a
+ /// listening 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.
///
/// This value is ignored if the connection is created by
- /// container::listen.
+ /// `container::listen`.
PN_CPP_EXTERN connection_options& password(const std::string&);
/// Set SSL client options.
@@ -146,10 +150,9 @@ class connection_options {
/// **Unsettled API** - Set the SASL configuration path.
PN_CPP_EXTERN connection_options& sasl_config_path(const std::string&);
- /// **Experimental** - Options for reconnect on outgoing connections.
+ /// **Unsettled API** - Set reconnect and failover options.
PN_CPP_EXTERN connection_options& reconnect(reconnect_options &);
-
/// Update option values from values set in other.
PN_CPP_EXTERN connection_options& update(const connection_options& other);
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 d447abe..01952c6 100644
--- a/proton-c/bindings/cpp/include/proton/container.hpp
+++ b/proton-c/bindings/cpp/include/proton/container.hpp
@@ -32,7 +32,11 @@
#include <string>
-/// If the library can support multithreaded containers then PN_CPP_SUPPORTS_THREADS will be set.
+/// @file
+/// @copybrief proton::container
+
+/// If the library can support multithreaded containers, then
+/// PN_CPP_SUPPORTS_THREADS will be set.
#define PN_CPP_SUPPORTS_THREADS PN_CPP_HAS_STD_THREAD && PN_CPP_HAS_STD_MUTEX && PN_CPP_HAS_STD_ATOMIC
namespace proton {
@@ -51,66 +55,76 @@ namespace proton {
class PN_CPP_CLASS_EXTERN container {
public:
/// Create a container.
- PN_CPP_EXTERN container(messaging_handler& h, const std::string& id="");
+ PN_CPP_EXTERN container(messaging_handler&, const std::string& id="");
/// Create a container.
PN_CPP_EXTERN container(const std::string& id="");
/// Destroy a container.
- /// Note that you may not delete a container from within any of the threads running
- /// any of the container's messaging_handlers. Specifically if you delete the container
- /// from within a handler you cause a deadlock or a crash.
///
- /// The only safe place to delete a container is after all of the threads running a container
- /// have finished and all of the run functions have returned.
+ /// It is unsafe to delete a container from within any of the
+ /// threads running a messaging_handler. Deleting the container
+ /// from within a handler will cause a deadlock or a crash. The
+ /// only safe place to delete a container is after all of the
+ /// threads running a container have finished and all of the run
+ /// functions have returned.
PN_CPP_EXTERN ~container();
- /// Connect to `url` and send an open request to the remote peer.
+ /// Connect to `conn_url` and send an open request to the remote peer.
///
- /// Options are applied to the connection as follows, values in later
- /// options override earlier ones:
+ /// Options are applied to the connection as follows. Values in
+ /// later options override earlier ones.
///
/// 1. client_connection_options()
- /// 2. options passed to connect()
+ /// 2. Options passed to connect()
///
/// The handler in the composed options is used to call
- /// proton::messaging_handler::on_connection_open() when the remote peer's
- /// open response is received.
+ /// messaging_handler::on_connection_open() when the open response
+ /// is received from the remote peer.
+ ///
+ /// @return returned<connection>
///
- /// @return A returned<connection>
/// @copydetails returned
- PN_CPP_EXTERN returned<connection> connect(const std::string& url, const connection_options &);
+ PN_CPP_EXTERN returned<connection> connect(const std::string& conn_url,
+ const connection_options&);
- /// Connect to `url` and send an open request to the remote peer.
- /// @return A returned<connection>
+ /// Connect to `conn_url` and send an open request to the remote peer.
+ ///
+ /// @return returned<connection>
+ ///
/// @copydetails returned
- PN_CPP_EXTERN returned<connection> connect(const std::string& url);
+ PN_CPP_EXTERN returned<connection> connect(const std::string& conn_url);
- /// Start listening on url.
+ /// Start listening on `listen_url`.
///
/// Calls to the @ref listen_handler are serialized for this listener,
/// but handlers attached to separate listeners may be called concurrently.
///
- /// @param url identifies a listening url.
- /// @param lh handles listening events
- /// @return listener lets you stop listening
- PN_CPP_EXTERN listener listen(const std::string& url, listen_handler& lh);
+ /// @return listener Lets you stop listening
+ PN_CPP_EXTERN listener listen(const std::string& listen_url,
+ listen_handler&);
- /// Listen with a fixed set of options for all accepted connections.
- /// See listen(const std::string&, listen_handler&)
- PN_CPP_EXTERN listener listen(const std::string& url, const connection_options&);
+ /// Listen with a fixed set of options for all accepted
+ /// connections. See listen(const std::string&, listen_handler&).
+ PN_CPP_EXTERN listener listen(const std::string& listen_url,
+ const connection_options&);
- /// Start listening on URL.
- /// New connections will use the handler from server_connection_options()
- PN_CPP_EXTERN listener listen(const std::string& url);
+ /// Start listening on `listen_url`.
+ ///
+ /// New connections will use the handler from
+ /// server_connection_options().
+ PN_CPP_EXTERN listener listen(const std::string& listen_url);
- /// Run the container in this thread.
- /// Returns when the container stops.
+ /// Run the container in this thread. The call returns when the
+ /// container stops.
+ ///
/// @see auto_stop() and stop().
///
- /// If you are using C++11 or later you may use a multithreaded container. In this case you may
- /// call run() in multiple threads to create a thread pool. Or aternatively call run with an
- /// integer parameter specifying the number of threads for the thread pool.
+ /// If you are using C++11 or later you can use a multithreaded
+ /// container. In this case you can call run() in multiple threads
+ /// to create a thread pool. Alternatively, you can call run with
+ /// an integer parameter specifying the number of threads for the
+ /// thread pool.
PN_CPP_EXTERN void run();
#if PN_CPP_SUPPORTS_THREADS
@@ -118,98 +132,109 @@ class PN_CPP_CLASS_EXTERN container {
PN_CPP_EXTERN void run(int threads);
#endif
- /// If true, stop the container when all active connections and listeners are closed.
- /// If false the container will keep running till stop() is called.
+ /// Enable or disable automatic container stop. It is enabled by
+ /// default.
///
- /// auto_stop is set by default when a new container is created.
+ /// If true, stop the container when all active connections and
+ /// listeners are closed. If false, the container will keep
+ /// running till stop() is called.
PN_CPP_EXTERN void auto_stop(bool);
- /// **Unsettled API** - Stop the container with an error_condition
- /// err.
+ /// Stop the container with an error_condition.
///
/// - Abort all open connections and listeners.
/// - Process final handler events and injected functions
/// - If `!err.empty()`, handlers will receive on_transport_error
/// - run() will return in all threads.
- PN_CPP_EXTERN void stop(const error_condition& err);
+ PN_CPP_EXTERN void stop(const error_condition&);
- /// **Unsettled API** - Stop the container with an empty error
- /// condition.
+ /// Stop the container with an empty error condition.
///
/// @see stop(const error_condition&)
PN_CPP_EXTERN void stop();
- /// Open a connection and sender for `url`.
- /// @return A returned<sender>
+ /// Open a connection and sender for `addr_url`.
+ ///
+ /// @return returned<sender>
+ ///
/// @copydetails returned
- PN_CPP_EXTERN returned<sender> open_sender(const std::string &url);
+ PN_CPP_EXTERN returned<sender> open_sender(const std::string& addr_url);
- /// Open a connection and sender for `url`.
+ /// Open a connection and sender for `addr_url`.
///
/// Supplied sender options will override the container's
/// template options.
- /// @return A returned<sender>
+ ///
+ /// @return returned<sender>
+ ///
/// @copydetails returned
- PN_CPP_EXTERN returned<sender> open_sender(const std::string &url,
- const proton::sender_options &o);
+ PN_CPP_EXTERN returned<sender> open_sender(const std::string& addr_url,
+ const proton::sender_options&);
- /// Open a connection and sender for `url`.
+ /// Open a connection and sender for `addr_url`.
///
/// Supplied connection options will override the
/// container's template options.
- /// @return A returned<sender>
+ ///
+ /// @return returned<sender>
+ ///
/// @copydetails returned
- PN_CPP_EXTERN returned<sender> open_sender(const std::string &url,
- const connection_options &c);
+ PN_CPP_EXTERN returned<sender> open_sender(const std::string& addr_url,
+ const connection_options&);
- /// Open a connection and sender for `url`.
+ /// Open a connection and sender for `addr_url`.
///
/// Supplied sender or connection options will override the
/// container's template options.
///
- /// @return A returned<sender>
+ /// @return returned<sender>
+ ///
/// @copydetails returned
- PN_CPP_EXTERN returned<sender> open_sender(const std::string &url,
- const proton::sender_options &o,
- const connection_options &c);
+ PN_CPP_EXTERN returned<sender> open_sender(const std::string& addr_url,
+ const proton::sender_options&,
+ const connection_options&);
- /// Open a connection and receiver for `url`.
+ /// Open a connection and receiver for `addr_url`.
+ ///
+ /// @return returned<receiver>
///
- /// @return A returned<receiver>
/// @copydetails returned
- PN_CPP_EXTERN returned<receiver> open_receiver(const std::string&url);
+ PN_CPP_EXTERN returned<receiver> open_receiver(const std::string& addr_url);
- /// Open a connection and receiver for `url`.
+ /// Open a connection and receiver for `addr_url`.
///
/// Supplied receiver options will override the container's
/// template options.
///
- /// @return A returned<receiver>
+ /// @return returned<receiver>
+ ///
/// @copydetails returned
- PN_CPP_EXTERN returned<receiver> open_receiver(const std::string&url,
- const proton::receiver_options &o);
+ PN_CPP_EXTERN returned<receiver> open_receiver(const std::string& addr_url,
+ const proton::receiver_options&);
- /// Open a connection and receiver for `url`.
+ /// Open a connection and receiver for `addr_url`.
///
/// Supplied receiver or connection options will override the
/// container's template options.
///
- /// @return A returned<receiver>
+ /// @return returned<receiver>
+ ///
/// @copydetails returned
- PN_CPP_EXTERN returned<receiver> open_receiver(const std::string&url,
- const connection_options &c);
+ PN_CPP_EXTERN returned<receiver> open_receiver(const std::string& addr_url,
+ const connection_options&);
- /// Open a connection and receiver for `url`.
+ /// Open a connection and receiver for `addr_url`.
///
/// Supplied receiver or connection options will override the
/// container's template options.
///
- /// @return A returned<receiver>
+ /// @return returned<receiver>
+ ///
/// @copydetails returned
- PN_CPP_EXTERN returned<receiver> open_receiver(const std::string&url,
- const proton::receiver_options &o,
- const connection_options &c);
+ PN_CPP_EXTERN returned<receiver> open_receiver(const std::string& addr_url,
+ const proton::receiver_options&,
+ const connection_options&);
/// A unique identifier for the container.
PN_CPP_EXTERN std::string id() const;
@@ -217,7 +242,7 @@ class PN_CPP_CLASS_EXTERN container {
/// Connection options that will be to outgoing connections. These
/// are applied first and overriden by options provided in
/// connect() and messaging_handler::on_connection_open().
- PN_CPP_EXTERN void client_connection_options(const connection_options &);
+ PN_CPP_EXTERN void client_connection_options(const connection_options&);
/// @copydoc client_connection_options
PN_CPP_EXTERN connection_options client_connection_options() const;
@@ -226,7 +251,7 @@ class PN_CPP_CLASS_EXTERN container {
/// connections. These are applied first and overridden by options
/// provided in listen(), listen_handler::on_accept() and
/// messaging_handler::on_connection_open().
- PN_CPP_EXTERN void server_connection_options(const connection_options &);
+ PN_CPP_EXTERN void server_connection_options(const connection_options&);
/// @copydoc server_connection_options
PN_CPP_EXTERN connection_options server_connection_options() const;
@@ -234,7 +259,7 @@ class PN_CPP_CLASS_EXTERN container {
/// Sender options applied to senders created by this
/// container. They are applied before messaging_handler::on_sender_open()
/// and can be overridden.
- PN_CPP_EXTERN void sender_options(const class sender_options &);
+ PN_CPP_EXTERN void sender_options(const class sender_options&);
/// @copydoc sender_options
PN_CPP_EXTERN class sender_options sender_options() const;
@@ -242,26 +267,27 @@ class PN_CPP_CLASS_EXTERN container {
/// Receiver options applied to receivers created by this
/// container. They are applied before messaging_handler::on_receiver_open()
/// and can be overridden.
- PN_CPP_EXTERN void receiver_options(const class receiver_options &);
+ PN_CPP_EXTERN void receiver_options(const class receiver_options&);
/// @copydoc receiver_options
PN_CPP_EXTERN class receiver_options receiver_options() const;
- /// Schedule a piece of work to happen after the duration:
- /// The piece of work can be created from a function object.
- /// for C++11 and on use a std::function<void()> type; for
- /// C++03 compatibility you can use void_function0&
+ /// Schedule a piece of work to happen after a duration. The
+ /// piece of work can be created from a function object. For
+ /// C++11 and on use a `std::function<void()>` type.
PN_CPP_EXTERN void schedule(duration, work);
private:
class impl;
internal::pn_unique_ptr<impl> impl_;
+ /// @cond INTERNAL
friend class connection_options;
friend class session_options;
friend class receiver_options;
friend class sender_options;
friend class work_queue;
+ /// @endcond
};
} // proton
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/decimal.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/decimal.hpp b/proton-c/bindings/cpp/include/proton/decimal.hpp
index efca029..86c9013 100644
--- a/proton-c/bindings/cpp/include/proton/decimal.hpp
+++ b/proton-c/bindings/cpp/include/proton/decimal.hpp
@@ -28,36 +28,37 @@
#include <iosfwd>
-namespace proton {
-
-/// @name AMQP decimal types.
+/// @file
///
-/// AMQP uses the standard IEEE 754-2008 encoding for decimal types.
+/// AMQP decimal types.
///
-/// This library does not provide support for decimal arithmetic but it does
-/// provide access to the byte representation of decimal values. You can pass
-/// these values uninterpreted via AMQP, or you can use a library that supports
-/// IEEE 754-2008 and make a byte-wise copy between the real decimal values and
-/// proton::decimal values.
+/// AMQP uses the standard IEEE 754-2008 encoding for decimal types.
///
-/// @{
+/// This library does not provide support for decimal arithmetic, but
+/// it does provide access to the byte representation of decimal
+/// values. You can pass these values uninterpreted via AMQP, or you
+/// can use a library that supports IEEE 754-2008 and make a byte-wise
+/// copy between the real decimal values and `proton::decimal` values.
-/// 32-bit decimal floating point.
+namespace proton {
+
+/// A 32-bit decimal floating-point value.
class decimal32 : public byte_array<4> {};
-/// 64-bit decimal floating point.
+/// A 64-bit decimal floating-point value.
class decimal64 : public byte_array<8> {};
-/// 128-bit decimal floating point.
+/// A 128-bit decimal floating-point value.
class decimal128 : public byte_array<16> {};
-/// @}
-/// Print decimal values
-/// @{
+/// Print a 32-bit decimal value.
PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, const decimal32&);
+
+/// Print a 64-bit decimal value.
PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, const decimal64&);
+
+/// Print a 128-bit decimal value.
PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, const decimal128&);
-/// @}
} // proton
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/default_container.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/default_container.hpp b/proton-c/bindings/cpp/include/proton/default_container.hpp
index 633cfc9..3c84dc8 100644
--- a/proton-c/bindings/cpp/include/proton/default_container.hpp
+++ b/proton-c/bindings/cpp/include/proton/default_container.hpp
@@ -22,12 +22,13 @@
*
*/
+/// @file
+/// @copybrief proton::default_container
+
namespace proton {
-/// @cond INTERNAL
-/// default_container no longer exists as a separate class. Use `container`.
+/// **Deprecated** - Use `proton::container`.
typedef class container default_container;
-/// @endcond
} // proton
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 7a38bca..61a2fbe 100644
--- a/proton-c/bindings/cpp/include/proton/delivery.hpp
+++ b/proton-c/bindings/cpp/include/proton/delivery.hpp
@@ -27,6 +27,9 @@
#include "./internal/object.hpp"
#include "./transfer.hpp"
+/// @file
+/// @copybrief proton::delivery
+
namespace proton {
/// A received message.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/delivery_mode.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/delivery_mode.hpp b/proton-c/bindings/cpp/include/proton/delivery_mode.hpp
index 97b350f..744bd2c 100644
--- a/proton-c/bindings/cpp/include/proton/delivery_mode.hpp
+++ b/proton-c/bindings/cpp/include/proton/delivery_mode.hpp
@@ -22,6 +22,9 @@
*
*/
+/// @file
+/// @copybrief proton::delivery_mode
+
namespace proton {
/// The message delivery policy to establish when opening a link.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 a190cf9..626d02b 100644
--- a/proton-c/bindings/cpp/include/proton/duration.hpp
+++ b/proton-c/bindings/cpp/include/proton/duration.hpp
@@ -30,21 +30,24 @@
#include <iosfwd>
+/// @file
+/// @copybrief proton::duration
+
namespace proton {
/// A span of time in milliseconds.
class duration : private internal::comparable<duration> {
public:
- /// Numeric type used to store milliseconds
+ /// A numeric type holding a value in milliseconds.
typedef int64_t numeric_type;
- /// Construct from milliseconds
+ /// Construct from a value in milliseconds.
explicit duration(numeric_type ms = 0) : ms_(ms) {}
- /// Assign
+ /// Assign a value in milliseconds.
duration& operator=(numeric_type ms) { ms_ = ms; return *this; }
- /// Return milliseconds
+ /// Get the value in milliseconds.
numeric_type milliseconds() const { return ms_; }
PN_CPP_EXTERN static const duration FOREVER; ///< Wait forever
@@ -56,7 +59,7 @@ class duration : private internal::comparable<duration> {
numeric_type ms_;
};
-/// Print duration
+/// Print a duration.
PN_CPP_EXTERN std::ostream& operator<<(std::ostream&, duration);
/// @name Comparison and arithmetic operators
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 d660762..0192454 100644
--- a/proton-c/bindings/cpp/include/proton/endpoint.hpp
+++ b/proton-c/bindings/cpp/include/proton/endpoint.hpp
@@ -27,6 +27,9 @@
#include "./internal/config.hpp"
#include "./internal/export.hpp"
+/// @file
+/// @copybrief proton::endpoint
+
namespace proton {
/// The base class for session, connection, and link.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 6896620..53643ba 100644
--- a/proton-c/bindings/cpp/include/proton/error.hpp
+++ b/proton-c/bindings/cpp/include/proton/error.hpp
@@ -28,6 +28,9 @@
#include <stdexcept>
#include <string>
+/// @file
+/// @copybrief proton::error
+
namespace proton {
/// The base Proton error.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 159356e..ac612f6 100644
--- a/proton-c/bindings/cpp/include/proton/error_condition.hpp
+++ b/proton-c/bindings/cpp/include/proton/error_condition.hpp
@@ -29,6 +29,9 @@
#include <string>
#include <iosfwd>
+/// @file
+/// @copybrief proton::error_condition
+
struct pn_condition_t;
namespace proton {
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/function.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/function.hpp b/proton-c/bindings/cpp/include/proton/function.hpp
index ac756c7..452ceaf 100644
--- a/proton-c/bindings/cpp/include/proton/function.hpp
+++ b/proton-c/bindings/cpp/include/proton/function.hpp
@@ -20,9 +20,16 @@
* under the License.
*/
+/// @file
+/// **Deprecated** - Use `proton::work`.
+
+/// @cond INTERNAL
+
namespace proton {
-/// A C++03 compatible void no-argument callback function object.
+/// **Deprecated** - Use `proton::work`.
+///
+/// A C++03-compatible void no-argument callback function object.
///
/// Used by container::schedule() and event_loop::inject(). In C++11
/// you can use std::bind, std::function or a void-no-argument lambda
@@ -39,6 +46,8 @@ class void_function0 {
virtual void operator()() = 0;
};
-}
+} // proton
+
+/// @endcond
#endif // PROTON_FUNCTION_HPP
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/proton-c/bindings/cpp/include/proton/fwd.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/fwd.hpp b/proton-c/bindings/cpp/include/proton/fwd.hpp
index a394579..679b974 100644
--- a/proton-c/bindings/cpp/include/proton/fwd.hpp
+++ b/proton-c/bindings/cpp/include/proton/fwd.hpp
@@ -22,6 +22,9 @@
*
*/
+/// @file
+/// Forward declarations.
+
namespace proton {
class annotation_key;
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 97f900a..fdbd368 100644
--- a/proton-c/bindings/cpp/include/proton/internal/data.hpp
+++ b/proton-c/bindings/cpp/include/proton/internal/data.hpp
@@ -34,13 +34,13 @@ class value;
namespace internal {
/// @cond INTERNAL
-/// Wrapper for a proton data object.
+/// A wrapper for a proton data object.
class data : public object<pn_data_t> {
- /// Wrap an existing proton-C data object.
+ /// Wrap an existing Proton-C data object.
data(pn_data_t* d) : internal::object<pn_data_t>(d) {}
public:
- /// Create an empty data.
+ /// Create an empty data object.
data() : internal::object<pn_data_t>(0) {}
/// Create a new data object.
@@ -78,10 +78,10 @@ class data : public object<pn_data_t> {
};
/// @endcond
-/// **Unsettled API** - 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.
+/// A state guard saves the state and restores it in the destructor
+/// unless `cancel()` is called.
struct state_guard {
/// @cond INTERNAL
data& data_;
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 a7e96fe..33026e0 100644
--- a/proton-c/bindings/cpp/include/proton/io/connection_driver.hpp
+++ b/proton-c/bindings/cpp/include/proton/io/connection_driver.hpp
@@ -32,6 +32,9 @@
#include <string>
+/// @file
+/// @copybrief proton::io::connection_driver
+
namespace proton {
class work_queue;
@@ -39,7 +42,8 @@ class proton_handler;
namespace io {
-/// **Unsettled API** - Pointer to a mutable memory region with a size.
+/// **Unsettled API** - A 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 +52,8 @@ struct mutable_buffer {
mutable_buffer(char* data_=0, size_t size_=0) : data(data_), size(size_) {}
};
-/// **Unsettled API** - Pointer to a const memory region with a size.
+/// **Unsettled API** - A pointer to an immutable 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.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/363d337b/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 eb28613..5c5280e 100644
--- a/proton-c/bindings/cpp/include/proton/link.hpp
+++ b/proton-c/bindings/cpp/include/proton/link.hpp
@@ -29,6 +29,9 @@
#include <string>
+/// @file
+/// @copybrief proton::link
+
struct pn_link_t;
namespace proton {
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org