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 2016/12/08 02:30:01 UTC
qpid-proton git commit: PROTON-1373: C++ API doc improvements
Repository: qpid-proton
Updated Branches:
refs/heads/master 1c7e70a28 -> bea617333
PROTON-1373: C++ API doc improvements
- Fix all warnings
- Expose C++11 API elements
- Improve presentation in class list
- Some simple corrections
Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo
Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/bea61733
Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/bea61733
Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/bea61733
Branch: refs/heads/master
Commit: bea617333ec36a97fc3079375d2574ea28de6b7e
Parents: 1c7e70a
Author: Justin Ross <jr...@apache.org>
Authored: Wed Dec 7 18:29:35 2016 -0800
Committer: Justin Ross <jr...@apache.org>
Committed: Wed Dec 7 18:29:35 2016 -0800
----------------------------------------------------------------------
proton-c/bindings/cpp/docs/user.doxygen.in | 2 +-
.../cpp/include/proton/codec/encoder.hpp | 4 ++--
.../bindings/cpp/include/proton/container.hpp | 9 +++++++--
.../cpp/include/proton/default_container.hpp | 4 ++++
.../bindings/cpp/include/proton/endpoint.hpp | 5 +++--
.../cpp/include/proton/error_condition.hpp | 4 +++-
.../bindings/cpp/include/proton/function.hpp | 14 ++++++++------
.../cpp/include/proton/internal/type_traits.hpp | 8 ++++----
.../include/proton/io/container_impl_base.hpp | 20 ++++++++++----------
proton-c/bindings/cpp/include/proton/sasl.hpp | 2 ++
.../bindings/cpp/include/proton/thread_safe.hpp | 7 ++++++-
proton-c/bindings/cpp/include/proton/url.hpp | 2 +-
12 files changed, 51 insertions(+), 30 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/bea61733/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 8ec4e47..a56eb98 100644
--- a/proton-c/bindings/cpp/docs/user.doxygen.in
+++ b/proton-c/bindings/cpp/docs/user.doxygen.in
@@ -43,7 +43,7 @@ ALPHABETICAL_INDEX = NO
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
-PREDEFINED = protected=private PN_CPP_EXTERN= PN_CPP_OVERRIDE=
+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
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/bea61733/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 24de309..222e95b 100644
--- a/proton-c/bindings/cpp/include/proton/codec/encoder.hpp
+++ b/proton-c/bindings/cpp/include/proton/codec/encoder.hpp
@@ -38,8 +38,8 @@ class value_base;
namespace codec {
-/// **Experimental** - Stream-like encoder from AMQP bytes to C++
-/// values.
+/// **Experimental** - Stream-like encoder from C++ values to AMQP
+/// bytes.
///
/// For internal use only.
///
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/bea61733/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 bc3a104..0c40f3d 100644
--- a/proton-c/bindings/cpp/include/proton/container.hpp
+++ b/proton-c/bindings/cpp/include/proton/container.hpp
@@ -46,8 +46,12 @@ namespace proton {
/// messages.
class PN_CPP_CLASS_EXTERN container {
public:
+ /// Create a container.
PN_CPP_EXTERN container(messaging_handler& h, const std::string& id="");
+
+ /// Create a container.
PN_CPP_EXTERN container(const std::string& id="");
+
PN_CPP_EXTERN ~container();
/// Connect to `url` and send an open request to the remote peer.
@@ -205,8 +209,9 @@ class PN_CPP_CLASS_EXTERN container {
/// @copydoc receiver_options
PN_CPP_EXTERN class receiver_options receiver_options() const;
- /// Schedule a function to be called after the duration.
- /// C++03 compatible, for C++11 use the schedule(duration, std::function<void()>)
+ /// Schedule a function to be called after the duration. C++03
+ /// compatible, for C++11 use schedule(duration,
+ /// std::function<void()>)
PN_CPP_EXTERN void schedule(duration, void_function0&);
#if PN_CPP_HAS_STD_FUNCTION
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/bea61733/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 3b3fce9..0f245a0 100644
--- a/proton-c/bindings/cpp/include/proton/default_container.hpp
+++ b/proton-c/bindings/cpp/include/proton/default_container.hpp
@@ -23,7 +23,11 @@
*/
namespace proton {
+
+/// @cond INTERNAL
typedef class container default_container;
+/// @endcond
+
} // proton
#endif // PROTON_DEFAULT_CONTAINER_HPP
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/bea61733/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 36ac981..b041906 100644
--- a/proton-c/bindings/cpp/include/proton/endpoint.hpp
+++ b/proton-c/bindings/cpp/include/proton/endpoint.hpp
@@ -62,13 +62,14 @@ PN_CPP_CLASS_EXTERN endpoint {
#if PN_CPP_HAS_DEFAULTED_FUNCTIONS
// Make everything explicit for C++11 compilers
-
+
+ /// @cond INTERNAL
endpoint() = default;
endpoint& operator=(const endpoint&) = default;
endpoint& operator=(endpoint&&) = default;
-
endpoint(const endpoint&) = default;
endpoint(endpoint&&) = default;
+ /// @endcond
#endif
};
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/bea61733/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 fb39332..fb0d461 100644
--- a/proton-c/bindings/cpp/include/proton/error_condition.hpp
+++ b/proton-c/bindings/cpp/include/proton/error_condition.hpp
@@ -55,16 +55,18 @@ class error_condition {
PN_CPP_EXTERN error_condition(std::string name, std::string description, proton::value properties);
#if PN_CPP_HAS_DEFAULTED_FUNCTIONS
+ /// @cond INTERNAL
error_condition(const error_condition&) = default;
error_condition(error_condition&&) = default;
error_condition& operator=(const error_condition&) = default;
error_condition& operator=(error_condition&&) = default;
+ /// @endcond
#endif
+#if PN_CPP_HAS_EXPLICIT_CONVERSIONS
/// If you are using a C++11 compiler, you may use an
/// error_condition in boolean contexts. The expression will be
/// true if the error_condition is set.
-#if PN_CPP_HAS_EXPLICIT_CONVERSIONS
PN_CPP_EXTERN explicit operator bool() const;
#endif
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/bea61733/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 4fbbe16..ac756c7 100644
--- a/proton-c/bindings/cpp/include/proton/function.hpp
+++ b/proton-c/bindings/cpp/include/proton/function.hpp
@@ -22,14 +22,16 @@
namespace proton {
-/// 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 instead.
+/// A C++03 compatible void no-argument callback function object.
///
-/// void_function0 is passed by reference, so instances of sub-classes do not
-/// have to be heap allocated. Once passed, the instance must not be deleted until
-/// its operator() is called or the container has stopped.
+/// Used by container::schedule() and event_loop::inject(). In C++11
+/// you can use std::bind, std::function or a void-no-argument lambda
+/// instead.
///
+/// void_function0 is passed by reference, so instances of sub-classes
+/// do not have to be heap allocated. Once passed, the instance must
+/// not be deleted until its operator() is called or the container has
+/// stopped.
class void_function0 {
public:
virtual ~void_function0() {}
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/bea61733/proton-c/bindings/cpp/include/proton/internal/type_traits.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/internal/type_traits.hpp b/proton-c/bindings/cpp/include/proton/internal/type_traits.hpp
index 4c4c7d6..8abba55 100644
--- a/proton-c/bindings/cpp/include/proton/internal/type_traits.hpp
+++ b/proton-c/bindings/cpp/include/proton/internal/type_traits.hpp
@@ -22,10 +22,10 @@
*
*/
-/// Type traits for mapping between AMQP and C++ types.
-///
-/// Also provides workarounds for missing type_traits classes on older
-/// C++ compilers.
+// Type traits for mapping between AMQP and C++ types.
+//
+// Also provides workarounds for missing type_traits classes on older
+// C++ compilers.
#include "./config.hpp"
#include "../types_fwd.hpp"
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/bea61733/proton-c/bindings/cpp/include/proton/io/container_impl_base.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/io/container_impl_base.hpp b/proton-c/bindings/cpp/include/proton/io/container_impl_base.hpp
index 0aeed78..a04b4ff 100644
--- a/proton-c/bindings/cpp/include/proton/io/container_impl_base.hpp
+++ b/proton-c/bindings/cpp/include/proton/io/container_impl_base.hpp
@@ -45,54 +45,54 @@ class container_impl_base : public standard_container {
using standard_container::open_receiver;
using standard_container::open_sender;
- /// @copydoc container::client_connection_options
+ /// @see proton::container::client_connection_options
void client_connection_options(const connection_options & opts) {
store(client_copts_, opts);
}
- /// @copydoc container::client_connection_options
+ /// @see proton::container::client_connection_options
connection_options client_connection_options() const {
return load(client_copts_);
}
- /// @copydoc container::server_connection_options
+ /// @see proton::container::server_connection_options
void server_connection_options(const connection_options & opts) {
store(server_copts_, opts);
}
- /// @copydoc container::server_connection_options
+ /// @see proton::container::server_connection_options
connection_options server_connection_options() const {
return load(server_copts_);
}
- /// @copydoc container::sender_options
+ /// @see proton::container::sender_options
void sender_options(const class sender_options & opts) {
store(sender_opts_, opts);
}
- /// @copydoc container::sender_options
+ /// @see proton::container::sender_options
class sender_options sender_options() const {
return load(sender_opts_);
}
- /// @copydoc container::receiver_options
+ /// @see proton::container::receiver_options
void receiver_options(const class receiver_options & opts) {
store(receiver_opts_, opts);
}
- /// @copydoc container::receiver_options
+ /// @see proton::container::receiver_options
class receiver_options receiver_options() const {
return load(receiver_opts_);
}
- /// @copydoc container::open_sender
+ /// @see proton::container::open_sender
returned<sender> open_sender(
const std::string &url, const class sender_options &opts, const connection_options &copts)
{
return open_link<sender, class sender_options>(url, opts, copts, &connection::open_sender);
}
- /// @copydoc container::open_receiver
+ /// @see proton::container::open_receiver
returned<receiver> open_receiver(
const std::string &url, const class receiver_options &opts, const connection_options &copts)
{
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/bea61733/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 137aa28..3857f06 100644
--- a/proton-c/bindings/cpp/include/proton/sasl.hpp
+++ b/proton-c/bindings/cpp/include/proton/sasl.hpp
@@ -46,7 +46,9 @@ class sasl {
sasl& operator=(sasl&&) = delete;
#endif
#if PN_CPP_HAS_DEFAULTED_FUNCTIONS
+ /// @cond INTERNAL
sasl(sasl&&) = default;
+ /// @endcond
#endif
/// The result of the SASL negotiation.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/bea61733/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 7851245..28aa3a6 100644
--- a/proton-c/bindings/cpp/include/proton/thread_safe.hpp
+++ b/proton-c/bindings/cpp/include/proton/thread_safe.hpp
@@ -113,7 +113,7 @@ class thread_safe : private internal::pn_ptr_base, private internal::endpoint_tr
/// @endcond
};
-// return value for functions returning a thread_safe<> object.
+// A return value for functions returning a thread_safe<> object.
//
// Temporary return value only, you should release() to get a plain pointer or
// assign to a smart pointer type.
@@ -161,12 +161,17 @@ class returned : private internal::endpoint_traits<T>
template <class T> returned<T> make_thread_safe(const T& obj) { return returned<T>(obj); }
#if PN_CPP_HAS_CPP11
+
+/// Create a thread-safe shared_ptr to `obj`.
template <class T> std::shared_ptr<thread_safe<T> > make_shared_thread_safe(const T& obj) {
return make_thread_safe(obj);
}
+
+/// Create a thread-safe unique_ptr to `obj`.
template <class T> std::unique_ptr<thread_safe<T> > make_unique_thread_safe(const T& obj) {
return make_thread_safe(obj);
}
+
#endif
} // proton
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/bea61733/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 52e8d43..b94b24d 100644
--- a/proton-c/bindings/cpp/include/proton/url.hpp
+++ b/proton-c/bindings/cpp/include/proton/url.hpp
@@ -41,7 +41,7 @@ PN_CPP_CLASS_EXTERN url_error : public error {
/// @endcond
};
-/// A Proton URL.
+/// A URL parser.
///
/// Proton URLs take the form
/// `<scheme>://<username>:<password>@<host>:<port>/<path>`.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org