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/go1 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-unsubscr...@qpid.apache.org For additional commands, e-mail: commits-h...@qpid.apache.org
