Repository: qpid-proton Updated Branches: refs/heads/master bbeb09603 -> f45cdced1
NO-JIRA: C API documentation - module descriptions. Added missing module descriptions. Rewrote some descriptions to be more informative and less repetative. E.g. "Link API for proton Engine" -> "One-way message link" Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/f45cdced Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/f45cdced Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/f45cdced Branch: refs/heads/master Commit: f45cdced118908f5da29a63d3d7dd6e6068d6115 Parents: bbeb096 Author: Alan Conway <[email protected]> Authored: Thu Nov 17 14:16:45 2016 -0500 Committer: Alan Conway <[email protected]> Committed: Thu Nov 17 14:16:45 2016 -0500 ---------------------------------------------------------------------- proton-c/docs/api/index.md | 24 +++++++++++------------- proton-c/include/proton/codec.h | 4 ++-- proton-c/include/proton/condition.h | 9 +++++---- proton-c/include/proton/connection.h | 3 ++- proton-c/include/proton/connection_driver.h | 6 ++++-- proton-c/include/proton/delivery.h | 4 ++-- proton-c/include/proton/disposition.h | 4 ++-- proton-c/include/proton/engine.h | 8 +++++--- proton-c/include/proton/event.h | 4 ++-- proton-c/include/proton/handlers.h | 1 + proton-c/include/proton/link.h | 7 ++++--- proton-c/include/proton/listener.h | 4 +++- proton-c/include/proton/message.h | 6 ++++-- proton-c/include/proton/messenger.h | 1 + proton-c/include/proton/proactor.h | 5 ++--- proton-c/include/proton/reactor.h | 1 + proton-c/include/proton/sasl.h | 8 +++++--- proton-c/include/proton/selectable.h | 1 + proton-c/include/proton/session.h | 6 ++++-- proton-c/include/proton/ssl.h | 10 +++++++--- proton-c/include/proton/terminus.h | 7 ++++--- proton-c/include/proton/transport.h | 6 ++++-- proton-c/include/proton/types.h | 4 ++++ proton-c/include/proton/url.h | 8 +++++--- 24 files changed, 85 insertions(+), 56 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/f45cdced/proton-c/docs/api/index.md ---------------------------------------------------------------------- diff --git a/proton-c/docs/api/index.md b/proton-c/docs/api/index.md index 6a72d6b..fada41c 100644 --- a/proton-c/docs/api/index.md +++ b/proton-c/docs/api/index.md @@ -1,21 +1,19 @@ Proton Documentation {#index} ==================== -The @ref engine is an AMQP "protocol engine". It provides functions to -manipulate AMQP endpoints and messages and generates [events](@ref event) for -the application to handle. The @ref engine has no dependencies on IO or -threading libraries. +The @ref engine is a collection of types and functions representing AMQP +concepts. Together they form a "protocol engine" API to create AMQP connections +and links, handle AMQP @ref event "events" and send and receive messages. -The @ref proactor is a proactive, asynchronous framework to -build single or multi-threaded Proton C applications. It manages the IO -transport layer so you can write portable, event-driven AMQP code using the -@ref engine API. +The @ref proactor is a portable, proactive, asynchronous API for single or +multi-threaded applications. It associates the @ref engine API with network +connections (@ref transport "transports") and allows one or more threads to +handle @ref event "events". -**Low-level integration**: The @ref connection_driver provides -a simple bytes in/bytes out interface to the @ref engine for a single -connection. You can use this to integrate proton with special IO libraries or -external event loops. It is also possible to write your own implementation of the -@ref proactor if you want to transparently replace proton's IO layer. +**Low-level integration**: The @ref connection\_driver provides a low-level SPI +to feed byte-streams from any source to the @ref 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. http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/f45cdced/proton-c/include/proton/codec.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/codec.h b/proton-c/include/proton/codec.h index 3f7e5ac..d8995fe 100644 --- a/proton-c/include/proton/codec.h +++ b/proton-c/include/proton/codec.h @@ -35,10 +35,10 @@ extern "C" { /** * @file - * - * Data API for proton. + * AMQP data encoding and decoding * * @defgroup data Data + * AMQP data encoding and decoding * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/f45cdced/proton-c/include/proton/condition.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/condition.h b/proton-c/include/proton/condition.h index ae2beff..0f0774b 100644 --- a/proton-c/include/proton/condition.h +++ b/proton-c/include/proton/condition.h @@ -31,12 +31,13 @@ extern "C" { #endif -/** @file - * - * The Condition API for the proton Engine. +/** + * @file + * Error condition * * @defgroup condition Condition - * @ingroup connection + * Error condition + * @ingroup engine * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/f45cdced/proton-c/include/proton/connection.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/connection.h b/proton-c/include/proton/connection.h index 5b966cd..19e882f 100644 --- a/proton-c/include/proton/connection.h +++ b/proton-c/include/proton/connection.h @@ -38,9 +38,10 @@ extern "C" { /** * @file * - * Connection API for the proton @ref engine + * AMQP protocol connection * * @defgroup connection Connection + * AMQP protocol connection * @ingroup engine * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/f45cdced/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 8a5132b..af08160 100644 --- a/proton-c/include/proton/connection_driver.h +++ b/proton-c/include/proton/connection_driver.h @@ -22,11 +22,13 @@ /** * @file + * **Experimental**: Low-level IO integration * * @defgroup connection_driver Connection Driver * - * **Experimental**: Toolkit for integrating proton with arbitrary network or IO - * transports via a bytes-in, bytes-out interface. + * **Experimental**: Low-level IO integration + * + * Associate an @ref engine with AMQP byte-streams from any source. * * - process AMQP-encoded bytes from some input byte stream * - generate ::pn_event_t events for your application to handle http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/f45cdced/proton-c/include/proton/delivery.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/delivery.h b/proton-c/include/proton/delivery.h index 2642bd7..4225352 100644 --- a/proton-c/include/proton/delivery.h +++ b/proton-c/include/proton/delivery.h @@ -33,10 +33,10 @@ extern "C" { /** * @file - * - * Delivery API for the proton Engine. + * Track message delivery * * @defgroup delivery Delivery + * Track message delivery * @ingroup engine * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/f45cdced/proton-c/include/proton/disposition.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/disposition.h b/proton-c/include/proton/disposition.h index 202f996..530b738 100644 --- a/proton-c/include/proton/disposition.h +++ b/proton-c/include/proton/disposition.h @@ -33,10 +33,10 @@ extern "C" { /** * @file - * - * Disposition API for the proton Engine. + * Outcome of message delivery * * @defgroup disposition Disposition + * Outcome of message delivery * @ingroup delivery * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/f45cdced/proton-c/include/proton/engine.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/engine.h b/proton-c/include/proton/engine.h index 8f8719e..b24265e 100644 --- a/proton-c/include/proton/engine.h +++ b/proton-c/include/proton/engine.h @@ -22,12 +22,14 @@ * */ -/** @file +/** + * @file * - * The proton Engine API. The Engine API provides a complete - * implementation of AMQP as a Protocol Engine. + * The AMQP protocol engine * * @defgroup engine Engine + * + * Types and functions that implement the AMQP protocol */ #include <proton/condition.h> http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/f45cdced/proton-c/include/proton/event.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/event.h b/proton-c/include/proton/event.h index 7793f1c..2280dc8 100644 --- a/proton-c/include/proton/event.h +++ b/proton-c/include/proton/event.h @@ -33,10 +33,10 @@ extern "C" { /** * @file - * - * Event API for the proton Engine. + * AMQP and transport events * * @defgroup event Event + * AMQP and transport events * @ingroup engine * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/f45cdced/proton-c/include/proton/handlers.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/handlers.h b/proton-c/include/proton/handlers.h index a8a6f77..bfa68fc 100644 --- a/proton-c/include/proton/handlers.h +++ b/proton-c/include/proton/handlers.h @@ -36,6 +36,7 @@ extern "C" { * Reactor API for proton. * * @defgroup handlers Handlers + * Reactor API for proton. * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/f45cdced/proton-c/include/proton/link.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/link.h b/proton-c/include/proton/link.h index 1ac2270..3ab811c 100644 --- a/proton-c/include/proton/link.h +++ b/proton-c/include/proton/link.h @@ -36,10 +36,10 @@ extern "C" { /** * @file - * - * Link API for the proton Engine. + * One-way message link * * @defgroup link Link + * One-way message link * @ingroup engine * @{ */ @@ -566,6 +566,7 @@ PN_EXTERN pn_delivery_t *pn_unsettled_next(pn_delivery_t *delivery); /** * @defgroup sender Sender + * Sending link * @{ */ @@ -592,9 +593,9 @@ PN_EXTERN ssize_t pn_link_send(pn_link_t *sender, const char *bytes, size_t n); /** @} */ -// receiver /** * @defgroup receiver Receiver + * Receiving link * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/f45cdced/proton-c/include/proton/listener.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/listener.h b/proton-c/include/proton/listener.h index 4244e69..cd3d95f 100644 --- a/proton-c/include/proton/listener.h +++ b/proton-c/include/proton/listener.h @@ -29,9 +29,11 @@ extern "C" { /** * @file * - * Listener API for the proton @ref proactor + * Listener for the @ref proactor * * @defgroup listener Listener + * Listen for incoming connections with a @ref proactor + * * @ingroup proactor * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/f45cdced/proton-c/include/proton/message.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/message.h b/proton-c/include/proton/message.h index 837b95e..8741996 100644 --- a/proton-c/include/proton/message.h +++ b/proton-c/include/proton/message.h @@ -32,10 +32,12 @@ extern "C" { #endif -/** @file - * Message API for encoding/decoding AMQP Messages. +/** + * @file + * Encode/decode AMQP Messages * * @defgroup message Message + * Encode/decode AMQP Messages * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/f45cdced/proton-c/include/proton/messenger.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/messenger.h b/proton-c/include/proton/messenger.h index 8cba51d..198b6c6 100644 --- a/proton-c/include/proton/messenger.h +++ b/proton-c/include/proton/messenger.h @@ -40,6 +40,7 @@ extern "C" { * receiving AMQP messages. * * @defgroup messenger Messenger + * **Deprecated** * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/f45cdced/proton-c/include/proton/proactor.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/proactor.h b/proton-c/include/proton/proactor.h index 8a2680b..cd44526 100644 --- a/proton-c/include/proton/proactor.h +++ b/proton-c/include/proton/proactor.h @@ -33,11 +33,10 @@ typedef struct pn_condition_t pn_condition_t; /** * @file * - * **Experimental**: Proactor API for the the proton @ref engine - * + * **Experimental**: Multi-threaded IO * @defgroup proactor Proactor * - * **Experimental**: Proactor API for portable, multi-threaded, asynchronous applications. + * **Experimental**: Multi-threaded IO * * The proactor associates a @ref connection with a @ref transport, either * by making an outgoing connection or accepting an incoming one. http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/f45cdced/proton-c/include/proton/reactor.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/reactor.h b/proton-c/include/proton/reactor.h index bfd6de5..b61ea7a 100644 --- a/proton-c/include/proton/reactor.h +++ b/proton-c/include/proton/reactor.h @@ -40,6 +40,7 @@ extern "C" { * Reactor API for proton. * * @defgroup reactor Reactor + * Reactor API for proton. * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/f45cdced/proton-c/include/proton/sasl.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/sasl.h b/proton-c/include/proton/sasl.h index 354982f..e8e0d96 100644 --- a/proton-c/include/proton/sasl.h +++ b/proton-c/include/proton/sasl.h @@ -30,16 +30,18 @@ extern "C" { #endif -/** @file - * API for the SASL Secure Transport Layer. +/** + * @file + * SASL Secure Transport Layer. * + * @defgroup sasl SASL + * SASL Secure Transport Layer. * The SASL layer is responsible for establishing an authenticated * and/or encrypted tunnel over which AMQP frames are passed between * peers. The peer acting as the SASL Client must provide * authentication credentials. The peer acting as the SASL Server must * provide authentication against the received credentials. * - * @defgroup sasl SASL * @ingroup transport * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/f45cdced/proton-c/include/proton/selectable.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/selectable.h b/proton-c/include/proton/selectable.h index 5eff58d..c6e7489 100644 --- a/proton-c/include/proton/selectable.h +++ b/proton-c/include/proton/selectable.h @@ -38,6 +38,7 @@ extern "C" { * party event loops. * * @defgroup selectable Selectable + * **Deprecated** * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/f45cdced/proton-c/include/proton/session.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/session.h b/proton-c/include/proton/session.h index 94d2869..34f0cfd 100644 --- a/proton-c/include/proton/session.h +++ b/proton-c/include/proton/session.h @@ -34,10 +34,12 @@ extern "C" { #endif -/** @file - * Session API for the proton Engine. +/** + * @file + * Serialized session * * @defgroup session Session + * Serialized session * @ingroup engine * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/f45cdced/proton-c/include/proton/ssl.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/ssl.h b/proton-c/include/proton/ssl.h index 8fdae08..420459a 100644 --- a/proton-c/include/proton/ssl.h +++ b/proton-c/include/proton/ssl.h @@ -30,7 +30,13 @@ extern "C" { #endif -/** @file +/** + * @file + * API for using SSL with the Transport Layer. + * + * @defgroup ssl SSL + * @ingroup transport + * * API for using SSL with the Transport Layer. * * A Transport may be configured to use SSL for encryption and/or authentication. A @@ -68,8 +74,6 @@ extern "C" { * Support for SSL Client Session resume is provided (see ::pn_ssl_init, * ::pn_ssl_resume_status). * - * @defgroup ssl SSL - * @ingroup transport * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/f45cdced/proton-c/include/proton/terminus.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/terminus.h b/proton-c/include/proton/terminus.h index b4bf6f8..43d4d98 100644 --- a/proton-c/include/proton/terminus.h +++ b/proton-c/include/proton/terminus.h @@ -31,11 +31,12 @@ extern "C" { #endif -/** @file - * - * Terminus API for the proton Engine. +/** + * @file + * Message terminus (source or target) * * @defgroup terminus Terminus + * Message terminus (source or target) * @ingroup link * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/f45cdced/proton-c/include/proton/transport.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/transport.h b/proton-c/include/proton/transport.h index 5c8494c..9683a42 100644 --- a/proton-c/include/proton/transport.h +++ b/proton-c/include/proton/transport.h @@ -33,10 +33,12 @@ extern "C" { /** * @file - * - * Transport API for the proton Engine. + * Network transport * * @defgroup transport Transport + * Network transport + * + * State of a network connection being used as a transport for an AMQP connection. * @ingroup engine * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/f45cdced/proton-c/include/proton/types.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/types.h b/proton-c/include/proton/types.h index 378719c..190f089 100644 --- a/proton-c/include/proton/types.h +++ b/proton-c/include/proton/types.h @@ -29,8 +29,10 @@ /** * @file + * AMQP type system * * @defgroup types Types + * AMQP type system * @{ */ @@ -40,6 +42,7 @@ extern "C" { /** * @defgroup primitives Primitive Types + * Primitive types * @{ */ @@ -83,6 +86,7 @@ static const pn_bytes_t pn_rwbytes_null = { 0, NULL }; /** * @defgroup abstract Abstract Types + * Abstract types * @{ */ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/f45cdced/proton-c/include/proton/url.h ---------------------------------------------------------------------- diff --git a/proton-c/include/proton/url.h b/proton-c/include/proton/url.h index 2a68bc2..4ff9536 100644 --- a/proton-c/include/proton/url.h +++ b/proton-c/include/proton/url.h @@ -26,11 +26,13 @@ extern "C" { #endif -/** @file - * URL API for parsing URLs. +/** + * @file + * Parsing URLs. * * @defgroup url URL - * @{ + * Parsing URLs. +! * @{ */ /** A parsed URL */ --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
