PROTON-1367: Adjust deprecations; improve rendered doc output
Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/140cf997 Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/140cf997 Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/140cf997 Branch: refs/heads/go1 Commit: 140cf99744406804a5b5754baa99fd1af9e21d08 Parents: 7bae475 Author: Justin Ross <jr...@apache.org> Authored: Fri Dec 2 13:05:27 2016 -0800 Committer: Justin Ross <jr...@apache.org> Committed: Fri Dec 2 13:05:27 2016 -0800 ---------------------------------------------------------------------- examples/c/proactor/README.dox | 32 +++++----- proton-c/docs/api/index.md | 18 +++--- proton-c/docs/api/user.doxygen.in | 19 ++++-- proton-c/include/proton/codec.h | 22 ++++--- proton-c/include/proton/condition.h | 10 +++- proton-c/include/proton/connection.h | 4 ++ proton-c/include/proton/connection_driver.h | 2 +- proton-c/include/proton/delivery.h | 2 + proton-c/include/proton/disposition.h | 2 + proton-c/include/proton/error.h | 2 + proton-c/include/proton/event.h | 2 + proton-c/include/proton/handlers.h | 2 - proton-c/include/proton/link.h | 4 ++ proton-c/include/proton/message.h | 2 + proton-c/include/proton/messenger.h | 6 +- proton-c/include/proton/reactor.h | 2 - proton-c/include/proton/sasl.h | 2 + proton-c/include/proton/selectable.h | 2 - proton-c/include/proton/session.h | 4 ++ proton-c/include/proton/ssl.h | 2 + proton-c/include/proton/terminus.h | 2 + proton-c/include/proton/transport.h | 76 ++++++++++++------------ proton-c/include/proton/types.h | 22 ++++--- proton-c/include/proton/url.h | 3 +- 24 files changed, 144 insertions(+), 100 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/140cf997/examples/c/proactor/README.dox ---------------------------------------------------------------------- diff --git a/examples/c/proactor/README.dox b/examples/c/proactor/README.dox index 9817267..4b09cb7 100644 --- a/examples/c/proactor/README.dox +++ b/examples/c/proactor/README.dox @@ -1,15 +1,17 @@ -/// @example send.c -/// -/// Send a fixed number of messages to the "example" node. -/// -/// @example receive.c -/// -/// Subscribes to the 'example' node and prints the message bodies -/// received. -/// -/// @example broker.c -/// -/// A simple multi-threaded broker that works with the send and -/// receive examples. -/// -/// __Requires C++11__ +/** + * @example send.c + * + * Send a fixed number of messages to the "example" node. + * + * @example receive.c + * + * Subscribes to the 'example' node and prints the message bodies + * received. + * + * @example broker.c + * + * A simple multithreaded broker that works with the send and receive + * examples. + * + * __Requires C++11__ + */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/140cf997/proton-c/docs/api/index.md ---------------------------------------------------------------------- diff --git a/proton-c/docs/api/index.md b/proton-c/docs/api/index.md index 2936278..cf35c33 100644 --- a/proton-c/docs/api/index.md +++ b/proton-c/docs/api/index.md @@ -1,5 +1,9 @@ # 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 @@ -9,7 +13,8 @@ receive @ref message "messages". ## Types -@ref types contains Protocol and API data types. +@ref types contains C data types, including @ref amqp\_types and @ref +api\_types. ## Codec @@ -17,7 +22,7 @@ receive @ref message "messages". ## IO -@ref io holds interfaces for IO integration. +@ref io holds interfaces for integrating Proton with platform IO. The @ref proactor is a portable, proactive, asynchronous API for single- or multithreaded applications. It associates AMQP @ref @@ -30,12 +35,3 @@ 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. - -<!-- - -**Old APIs** - The @ref messenger and @ref reactor APIs are older APIs -that were limited to single-threaded applications. @ref reactor -applications can be converted to use the @ref proactor since most of -the code is written to the common @ref engine API. - ---> http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/140cf997/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 2d4d815..7c4a771 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" +PROJECT_NAME = "Qpid Proton C API" PROJECT_NUMBER = @PN_VERSION_MAJOR@.@PN_VERSION_MINOR@.@PN_VERSION_POINT@ OUTPUT_DIRECTORY = . OUTPUT_LANGUAGE = English @@ -28,7 +28,7 @@ REPEAT_BRIEF = YES ALWAYS_DETAILED_SEC = NO INLINE_INHERITED_MEMB = YES JAVADOC_AUTOBRIEF = YES -MULTILINE_CPP_IS_BRIEF = NO +#MULTILINE_CPP_IS_BRIEF = NO INHERIT_DOCS = YES BUILTIN_STL_SUPPORT = YES INLINE_SIMPLE_STRUCTS = YES @@ -45,7 +45,7 @@ ENABLE_PREPROCESSING = YES MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = YES PREDEFINED = PN_EXTERN= PNX_EXTERN= -#EXCLUDE_SYMBOLS = +#EXCLUDE_SYMBOLS = # Configuration options related to warning and progress messages @@ -56,7 +56,17 @@ WARNINGS = YES INPUT = @CMAKE_SOURCE_DIR@/proton-c/include @CMAKE_SOURCE_DIR@/proton-c/docs @CMAKE_SOURCE_DIR@/examples/c FILE_PATTERNS = *.h *.md *.dox -# Don't parse example sources, only *. md and *.dox +EXCLUDE = \ + @CMAKE_SOURCE_DIR@/proton-c/include/proton/cid.h \ + @CMAKE_SOURCE_DIR@/proton-c/include/proton/engine.h \ + @CMAKE_SOURCE_DIR@/proton-c/include/proton/handlers.h \ + @CMAKE_SOURCE_DIR@/proton-c/include/proton/import_export.h \ + @CMAKE_SOURCE_DIR@/proton-c/include/proton/log.h \ + @CMAKE_SOURCE_DIR@/proton-c/include/proton/object.h \ + @CMAKE_SOURCE_DIR@/proton-c/include/proton/parser.h \ + @CMAKE_SOURCE_DIR@/proton-c/include/proton/reactor.h \ + @CMAKE_SOURCE_DIR@/proton-c/include/proton/selectable.h \ + @CMAKE_SOURCE_DIR@/proton-c/include/proton/type_compat.h EXCLUDE_PATTERNS = @CMAKE_SOURCE_DIR@/examples/*.c @CMAKE_SOURCE_DIR@/examples/*.h FULL_PATH_NAMES = YES RECURSIVE = YES @@ -71,6 +81,7 @@ GENERATE_TODOLIST = NO GENERATE_TESTLIST = NO GENERATE_BUGLIST = NO GENERATE_DEPRECATEDLIST = YES +IGNORE_PREFIX = pn_ PN_ # Configuration options related to the output format http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/140cf997/proton-c/include/proton/codec.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/codec.h b/proton-c/include/proton/codec.h index e812098..8f96774 100644 --- a/proton-c/include/proton/codec.h +++ b/proton-c/include/proton/codec.h @@ -35,6 +35,8 @@ extern "C" { /** * @file + * + * @copybrief codec */ /** @@ -190,14 +192,11 @@ typedef enum { PN_EXTERN const char *pn_type_name(pn_type_t type); /** - * @addtogroup codec - * @{ - */ - -/** * A descriminated union that holds any scalar AMQP value. The type * field indicates the AMQP type of the value, and the union may be * used to access the value for a given type. + * + * @ingroup api_types */ typedef struct { /** @@ -303,6 +302,11 @@ typedef struct { } pn_atom_t; /** + * @addtogroup data + * @{ + */ + +/** * An AMQP Data object. * * A pn_data_t object provides an interface for decoding, extracting, @@ -400,14 +404,14 @@ PN_EXTERN pn_error_t *pn_data_error(pn_data_t *data); /** * @cond INTERNAL - */ + */ PN_EXTERN int pn_data_vfill(pn_data_t *data, const char *fmt, va_list ap); PN_EXTERN int pn_data_fill(pn_data_t *data, const char *fmt, ...); PN_EXTERN int pn_data_vscan(pn_data_t *data, const char *fmt, va_list ap); PN_EXTERN int pn_data_scan(pn_data_t *data, const char *fmt, ...); /** * @endcond - */ + */ /** * Clears a pn_data_t object. @@ -482,11 +486,11 @@ PN_EXTERN bool pn_data_exit(pn_data_t *data); /** * @cond INTERNAL - */ + */ PN_EXTERN bool pn_data_lookup(pn_data_t *data, const char *name); /** * @endcond - */ + */ /** * Access the type of the current node. Returns PN_INVALID if there is no http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/140cf997/proton-c/include/proton/condition.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/condition.h b/proton-c/include/proton/condition.h index ee31b63..631a678 100644 --- a/proton-c/include/proton/condition.h +++ b/proton-c/include/proton/condition.h @@ -34,6 +34,8 @@ extern "C" { /** * @file * + * @copybrief condition + * * @addtogroup condition * @{ */ @@ -129,10 +131,14 @@ PN_EXTERN int pn_condition_set_description(pn_condition_t *condition, const char */ PN_EXTERN pn_data_t *pn_condition_info(pn_condition_t *condition); -/** Set the name and printf-style formatted description. */ +/** + * Set the name and printf-style formatted description. + */ PN_EXTERN int pn_condition_vformat(pn_condition_t *, const char *name, const char *fmt, va_list ap); -/** Set the name and printf-style formatted description. */ +/** + * Set the name and printf-style formatted description. + */ PN_EXTERN int pn_condition_format(pn_condition_t *, const char *name, const char *fmt, ...); /** http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/140cf997/proton-c/include/proton/connection.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/connection.h b/proton-c/include/proton/connection.h index 5dd04e4..748cd13 100644 --- a/proton-c/include/proton/connection.h +++ b/proton-c/include/proton/connection.h @@ -38,6 +38,8 @@ extern "C" { /** * @file * + * @copybrief connection + * * @addtogroup connection * @{ */ @@ -117,6 +119,8 @@ PN_EXTERN void pn_connection_free(pn_connection_t *connection); PN_EXTERN void pn_connection_release(pn_connection_t *connection); /** + * @deprecated + * * Get additional error information associated with the connection. * * Whenever a connection operation fails (i.e. returns an error code), http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/140cf997/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 9db8233..b34376d 100644 --- a/proton-c/include/proton/connection_driver.h +++ b/proton-c/include/proton/connection_driver.h @@ -23,7 +23,7 @@ /** * @file * - * **Experimental** - Low-level IO integration + * @copybrief connection_driver * * Associate a @ref connection and @ref transport with AMQP byte * streams from any source. http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/140cf997/proton-c/include/proton/delivery.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/delivery.h b/proton-c/include/proton/delivery.h index dbb73bf..209bf78 100644 --- a/proton-c/include/proton/delivery.h +++ b/proton-c/include/proton/delivery.h @@ -34,6 +34,8 @@ extern "C" { /** * @file * + * @copybrief delivery + * * @addtogroup delivery * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/140cf997/proton-c/include/proton/disposition.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/disposition.h b/proton-c/include/proton/disposition.h index 95bfe51..1d35db7 100644 --- a/proton-c/include/proton/disposition.h +++ b/proton-c/include/proton/disposition.h @@ -34,6 +34,8 @@ extern "C" { /** * @file * + * Delivery state + * * @addtogroup delivery * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/140cf997/proton-c/include/proton/error.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/error.h b/proton-c/include/proton/error.h index 2986850..c115ee1 100644 --- a/proton-c/include/proton/error.h +++ b/proton-c/include/proton/error.h @@ -32,6 +32,8 @@ extern "C" { /** * @file * + * @copybrief error + * * @addtogroup error * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/140cf997/proton-c/include/proton/event.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/event.h b/proton-c/include/proton/event.h index fad221b..4a88368 100644 --- a/proton-c/include/proton/event.h +++ b/proton-c/include/proton/event.h @@ -34,6 +34,8 @@ extern "C" { /** * @file * + * @copybrief event + * * @addtogroup event * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/140cf997/proton-c/include/proton/handlers.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/handlers.h b/proton-c/include/proton/handlers.h index 6518e87..feff0fe 100644 --- a/proton-c/include/proton/handlers.h +++ b/proton-c/include/proton/handlers.h @@ -31,8 +31,6 @@ extern "C" { #endif /** - * @file - * * @cond INTERNAL */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/140cf997/proton-c/include/proton/link.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/link.h b/proton-c/include/proton/link.h index aeb3b36..8ec162e 100644 --- a/proton-c/include/proton/link.h +++ b/proton-c/include/proton/link.h @@ -37,6 +37,8 @@ extern "C" { /** * @file * + * @copybrief link + * * @addtogroup link * @{ */ @@ -147,6 +149,8 @@ PN_EXTERN bool pn_link_is_receiver(pn_link_t *link); PN_EXTERN pn_state_t pn_link_state(pn_link_t *link); /** + * @deprecated + * * Get additional error information associated with the link. * * Whenever a link operation fails (i.e. returns an error code), http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/140cf997/proton-c/include/proton/message.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/message.h b/proton-c/include/proton/message.h index b047a43..5c310b0 100644 --- a/proton-c/include/proton/message.h +++ b/proton-c/include/proton/message.h @@ -35,6 +35,8 @@ extern "C" { /** * @file * + * @copybrief message + * * @addtogroup message * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/140cf997/proton-c/include/proton/messenger.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/messenger.h b/proton-c/include/proton/messenger.h index c11e7a5..74c3fc6 100644 --- a/proton-c/include/proton/messenger.h +++ b/proton-c/include/proton/messenger.h @@ -35,10 +35,10 @@ extern "C" { /** * @file - * @deprecated * - * The messenger API provides a high level interface for sending and - * receiving AMQP messages. + * @copybrief messenger + * + * @deprecated * * @addtogroup messenger * @{ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/140cf997/proton-c/include/proton/reactor.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/reactor.h b/proton-c/include/proton/reactor.h index 77d78e6..8d229ab 100644 --- a/proton-c/include/proton/reactor.h +++ b/proton-c/include/proton/reactor.h @@ -34,8 +34,6 @@ extern "C" { #endif /** - * @file - * * @cond INTERNAL */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/140cf997/proton-c/include/proton/sasl.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/sasl.h b/proton-c/include/proton/sasl.h index f5d6f2a..671ffec 100644 --- a/proton-c/include/proton/sasl.h +++ b/proton-c/include/proton/sasl.h @@ -33,6 +33,8 @@ extern "C" { /** * @file * + * @copybrief sasl + * * @addtogroup sasl * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/140cf997/proton-c/include/proton/selectable.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/selectable.h b/proton-c/include/proton/selectable.h index 56cccde..8c0a4db 100644 --- a/proton-c/include/proton/selectable.h +++ b/proton-c/include/proton/selectable.h @@ -32,8 +32,6 @@ extern "C" { #endif /** - * @file - * * @cond INTERNAL */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/140cf997/proton-c/include/proton/session.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/session.h b/proton-c/include/proton/session.h index 8cca7f6..8c78db4 100644 --- a/proton-c/include/proton/session.h +++ b/proton-c/include/proton/session.h @@ -37,6 +37,8 @@ extern "C" { /** * @file * + * @copybrief session + * * @addtogroup session * @{ */ @@ -108,6 +110,8 @@ PN_EXTERN pn_record_t *pn_session_attachments(pn_session_t *session); PN_EXTERN pn_state_t pn_session_state(pn_session_t *session); /** + * @deprecated + * * Get additional error information associated with the session. * * Whenever a session operation fails (i.e. returns an error code), http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/140cf997/proton-c/include/proton/ssl.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/ssl.h b/proton-c/include/proton/ssl.h index ee2997f..4e5a0ca 100644 --- a/proton-c/include/proton/ssl.h +++ b/proton-c/include/proton/ssl.h @@ -33,6 +33,8 @@ extern "C" { /** * @file * + * @copybrief ssl + * * @addtogroup ssl * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/140cf997/proton-c/include/proton/terminus.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/terminus.h b/proton-c/include/proton/terminus.h index 345bdda..c18fb3e 100644 --- a/proton-c/include/proton/terminus.h +++ b/proton-c/include/proton/terminus.h @@ -34,6 +34,8 @@ extern "C" { /** * @file * + * @copybrief terminus + * * @addtogroup terminus * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/140cf997/proton-c/include/proton/transport.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/transport.h b/proton-c/include/proton/transport.h index adb74bd..09fbb03 100644 --- a/proton-c/include/proton/transport.h +++ b/proton-c/include/proton/transport.h @@ -34,6 +34,8 @@ extern "C" { /** * @file * + * @copybrief transport + * * @addtogroup transport * @{ */ @@ -124,8 +126,6 @@ PN_EXTERN void pn_transport_set_server(pn_transport_t *transport); PN_EXTERN void pn_transport_free(pn_transport_t *transport); /** - * @deprecated - * * Retrieve the authenticated user. * * This is usually used at the the server end to find the name of the @@ -146,8 +146,6 @@ PN_EXTERN void pn_transport_free(pn_transport_t *transport); PN_EXTERN const char *pn_transport_get_user(pn_transport_t *transport); /** - * @deprecated - * * Set whether a non-authenticated transport connection is allowed. * * There are several ways within the AMQP protocol suite to get @@ -164,8 +162,6 @@ PN_EXTERN const char *pn_transport_get_user(pn_transport_t *transport); PN_EXTERN void pn_transport_require_auth(pn_transport_t *transport, bool required); /** - * @deprecated - * * Tell whether the transport connection is authenticated * * Note that this property may not be stable until the PN_CONNECTION_REMOTE_OPEN @@ -177,8 +173,6 @@ PN_EXTERN void pn_transport_require_auth(pn_transport_t *transport, bool require PN_EXTERN bool pn_transport_is_authenticated(pn_transport_t *transport); /** - * @deprecated - * * Set whether a non encrypted transport connection is allowed * * There are several ways within the AMQP protocol suite to get encrypted connections: @@ -193,8 +187,6 @@ PN_EXTERN bool pn_transport_is_authenticated(pn_transport_t *transport); PN_EXTERN void pn_transport_require_encryption(pn_transport_t *transport, bool required); /** - * @deprecated - * * Tell whether the transport connection is encrypted * * Note that this property may not be stable until the PN_CONNECTION_REMOTE_OPEN @@ -246,6 +238,8 @@ PN_EXTERN int pn_transport_unbind(pn_transport_t *transport); * * @param[in] transport a transport object * @param[in] trace the trace flags + * + * @internal XXX Deprecate! */ PN_EXTERN void pn_transport_trace(pn_transport_t *transport, pn_trace_t trace); @@ -258,6 +252,8 @@ PN_EXTERN void pn_transport_trace(pn_transport_t *transport, pn_trace_t trace); * * @param[in] transport a transport object * @param[in] tracer the tracing function + * + * @internal XXX Deprecate! */ PN_EXTERN void pn_transport_set_tracer(pn_transport_t *transport, pn_tracer_t tracer); @@ -266,6 +262,8 @@ PN_EXTERN void pn_transport_set_tracer(pn_transport_t *transport, pn_tracer_t tr * * @param[in] transport a transport object * @return the tracing function used by a transport + * + * @internal XXX Deprecate! */ PN_EXTERN pn_tracer_t pn_transport_get_tracer(pn_transport_t *transport); @@ -304,8 +302,6 @@ PN_EXTERN void pn_transport_set_context(pn_transport_t *transport, void *context PN_EXTERN pn_record_t *pn_transport_attachments(pn_transport_t *transport); /** - * @deprecated - * * Log a message using a transport's logging mechanism. * * This can be useful in a debugging context as the log message will @@ -313,12 +309,12 @@ PN_EXTERN pn_record_t *pn_transport_attachments(pn_transport_t *transport); * * @param[in] transport a transport object * @param[in] message the message to be logged + * + * @internal XXX Deprecate! */ PN_EXTERN void pn_transport_log(pn_transport_t *transport, const char *message); /** - * @deprecated - * * Log a printf formatted message using a transport's logging * mechanism. * @@ -328,12 +324,12 @@ PN_EXTERN void pn_transport_log(pn_transport_t *transport, const char *message); * @param[in] transport a transport object * @param[in] fmt the printf formatted message to be logged * @param[in] ap a vector containing the format arguments + * + * @internal XXX Deprecate! */ PN_EXTERN void pn_transport_vlogf(pn_transport_t *transport, const char *fmt, va_list ap); /** - * @deprecated - * * Log a printf formatted message using a transport's logging * mechanism. * @@ -342,33 +338,33 @@ PN_EXTERN void pn_transport_vlogf(pn_transport_t *transport, const char *fmt, va * * @param[in] transport a transport object * @param[in] fmt the printf formatted message to be logged + * + * @internal XXX Deprecate! */ PN_EXTERN void pn_transport_logf(pn_transport_t *transport, const char *fmt, ...); /** - * @deprecated - * * Get the maximum allowed channel for a transport. - * This will be the minimum of + * This will be the minimum of * 1. limit imposed by this proton implementation * 2. limit imposed by remote peer * 3. limit imposed by this application, using pn_transport_set_channel_max() * * @param[in] transport a transport object * @return the maximum allowed channel + * + * @internal XXX Deprecate! */ PN_EXTERN uint16_t pn_transport_get_channel_max(pn_transport_t *transport); /** - * @deprecated - * * Set the maximum allowed channel number for a transport. - * Note that this is the maximum channel number allowed, giving a - * valid channel number range of [0..channel_max]. Therefore the - * maximum number of simultaineously active channels will be + * Note that this is the maximum channel number allowed, giving a + * valid channel number range of [0..channel_max]. Therefore the + * maximum number of simultaineously active channels will be * channel_max plus 1. * You can call this function more than once to raise and lower - * the limit your application imposes on max channels for this + * the limit your application imposes on max channels for this * transport. However, smaller limits may be imposed by this * library, or by the remote peer. * After the OPEN frame has been sent to the remote peer, @@ -377,82 +373,84 @@ PN_EXTERN uint16_t pn_transport_get_channel_max(pn_transport_t *transport); * @param[in] transport a transport object * @param[in] channel_max the maximum allowed channel * @return PN_OK, or PN_STATE_ERR if it is too late to change channel_max + * + * @internal XXX Deprecate! */ PN_EXTERN int pn_transport_set_channel_max(pn_transport_t *transport, uint16_t channel_max); /** - * @deprecated - * * Get the maximum allowed channel of a transport's remote peer. * * @param[in] transport a transport object * @return the maximum allowed channel of the transport's remote peer + * + * @internal XXX Deprecate! */ PN_EXTERN uint16_t pn_transport_remote_channel_max(pn_transport_t *transport); /** - * @deprecated - * * Get the maximum frame size of a transport. * * @param[in] transport a transport object * @return the maximum frame size of the transport object + * + * @internal XXX Deprecate! */ PN_EXTERN uint32_t pn_transport_get_max_frame(pn_transport_t *transport); /** - * @deprecated - * * Set the maximum frame size of a transport. * * @param[in] transport a transport object * @param[in] size the maximum frame size for the transport object + * + * @internal XXX Deprecate! */ PN_EXTERN void pn_transport_set_max_frame(pn_transport_t *transport, uint32_t size); /** - * @deprecated - * * Get the maximum frame size of a transport's remote peer. * * @param[in] transport a transport object * @return the maximum frame size of the transport's remote peer + * + * @internal XXX Deprecate! */ PN_EXTERN uint32_t pn_transport_get_remote_max_frame(pn_transport_t *transport); /** - * @deprecated - * * Get the idle timeout for a transport. * * A zero idle timeout means heartbeats are disabled. * * @param[in] transport a transport object * @return the transport's idle timeout + * + * @internal XXX Deprecate! */ PN_EXTERN pn_millis_t pn_transport_get_idle_timeout(pn_transport_t *transport); /** - * @deprecated - * * Set the idle timeout for a transport. * * A zero idle timeout means heartbeats are disabled. * * @param[in] transport a transport object * @param[in] timeout the idle timeout for the transport object + * + * @internal XXX Deprecate! */ PN_EXTERN void pn_transport_set_idle_timeout(pn_transport_t *transport, pn_millis_t timeout); /** - * @deprecated - * * Get the idle timeout for a transport's remote peer. * * A zero idle timeout means heartbeats are disabled. * * @param[in] transport a transport object * @return the idle timeout for the transport's remote peer + * + * @internal XXX Deprecate! */ PN_EXTERN pn_millis_t pn_transport_get_remote_idle_timeout(pn_transport_t *transport); http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/140cf997/proton-c/include/proton/types.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/types.h b/proton-c/include/proton/types.h index 2ceadd3..c28beac 100644 --- a/proton-c/include/proton/types.h +++ b/proton-c/include/proton/types.h @@ -29,6 +29,8 @@ /** * @file * + * @copybrief types + * * @defgroup core Core * @brief Core protocol entities and event handling * @@ -77,34 +79,38 @@ * @ingroup core * * @defgroup error Error - * @brief A Proton error + * @brief A Proton API error * @ingroup core * * @defgroup types Types - * @brief Protocol and API data types + * @brief AMQP and API data types * - * @defgroup amqp_types AMQP types + * @defgroup amqp_types AMQP data types * @brief AMQP data types * @ingroup types * - * @defgroup api_types API types + * @defgroup api_types API data types * @brief Additional data types used in the API * @ingroup types * * @defgroup codec Codec * @brief AMQP data encoding and decoding * + * @defgroup data Data + * @brief A data structure for AMQP data + * @ingroup codec + * * @defgroup io IO * @brief IO integration interfaces * - * @defgroup connection_driver Connection Driver - * @brief **Experimental** - Low-level IO integration - * @ingroup io - * * @defgroup proactor Proactor * @brief **Experimental** - Multithreaded IO * @ingroup io * + * @defgroup connection_driver Connection driver + * @brief **Experimental** - Low-level IO integration + * @ingroup io + * * @defgroup messenger Messenger * @deprecated * @brief **Deprecated** - The Messenger API http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/140cf997/proton-c/include/proton/url.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/url.h b/proton-c/include/proton/url.h index 49faa30..e898aba 100644 --- a/proton-c/include/proton/url.h +++ b/proton-c/include/proton/url.h @@ -29,8 +29,7 @@ extern "C" { /** * @file * - * **Deprecated** - * + * @copybrief url * @deprecated * * @addtogroup url --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@qpid.apache.org For additional commands, e-mail: commits-h...@qpid.apache.org