You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by ac...@apache.org on 2016/11/17 19:18:15 UTC
qpid-proton git commit: NO-JIRA: C API documentation - module
descriptions.
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 <ac...@redhat.com>
Authored: Thu Nov 17 14:16:45 2016 -0500
Committer: Alan Conway <ac...@redhat.com>
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: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org