PROTON-1344: proactor documentation updates
diff --git a/proton-c/docs/api/index.md b/proton-c/docs/api/index.md
index 9c6009f..6a72d6b 100644
--- a/proton-c/docs/api/index.md
+++ b/proton-c/docs/api/index.md
@@ -1,35 +1,23 @@
Proton Documentation {#index}
====================
-## The Protocol Engine
+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 [Engine API](@ref engine) is a "pure AMQP" toolkit, it decodes AMQP bytes
-into proton [events](@ref event) and generates AMQP bytes from application
-calls. There is no IO or threading code in this part of the library.
-
-## Proactive event-driven programming
-
-The [Proactor API](@ref proactor) is a pro-active, asynchronous framework to
+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.
+transport layer so you can write portable, event-driven AMQP code using the
+@ref engine API.
-## IO Integration
+**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.
-The [connection driver](@ref connection_driver) provides a simple bytes in/bytes
-out, event-driven interface so you can read AMQP data from any source, process
-the resulting [events](@ref event) and write AMQP output to any destination. It
-lets you use proton in in alternate event loops, or for specialized embedded
-applications.
-
-It is also possible to write your own implementation of the @ref proactor if you
-are dealing with an unusual IO or threading framework. Any proton application
-written to the proactor API will be able to use your implementation.
-
-## Messenger and Reactor APIs (deprecated)
-
-The [Messenger](@ref messenger) [Reactor](@ref reactor) APIs are older APIs
-that were limited to single-threaded applications.
-
-Existing @ref reactor applications can be converted easily to use the @ref proactor,
-since they share the same @engine API and @ref event set.
+**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.
diff --git a/proton-c/include/proton/connection_driver.h b/proton-c/include/proton/connection_driver.h
index 4fa3fb9..8a5132b 100644
--- a/proton-c/include/proton/connection_driver.h
+++ b/proton-c/include/proton/connection_driver.h
@@ -26,8 +26,7 @@
* @defgroup connection_driver Connection Driver
*
* **Experimental**: Toolkit for integrating proton with arbitrary network or IO
- * transports. Provides a single point of control for an AMQP connection and
- * a simple bytes-in/bytes-out interface that lets you:
+ * transports via a bytes-in, bytes-out interface.
*
* - process AMQP-encoded bytes from some input byte stream
* - generate ::pn_event_t events for your application to handle
@@ -35,10 +34,10 @@
*
* The pn_connection_driver_() functions provide a simplified API and extra
* logic to use ::pn_connection_t and ::pn_transport_t as a unit. You can also
- * access them directly for features that are not exposed via the @ref
- * connection_driver API.
+ * access them directly for features that do not have pn_connection_driver_()
+ * functions
*
- * The engine buffers events and data, you should run it until
+ * The driver buffers events and data, you should run it until
* pn_connection_driver_finished() is true, to ensure all reading, writing and
* event handling (including ERROR and FINAL events) is finished.
*
@@ -62,7 +61,7 @@
*
* ## Thread safety
*
- * The @ref engine types are not thread safe, but each connection and its
+ * The @ref connection_driver types are not thread safe, but each connection and its
* associated types forms an independent unit. Different connections can be
* processed concurrently by different threads.
*
@@ -89,7 +88,7 @@
} pn_connection_driver_t;
/**
- * Set #connection and #transport to the provided values, or create a new
+ * Set connection and transport to the provided values, or create a new
* @ref pn_connection_t or @ref pn_transport_t if either is NULL.
* The provided values belong to the connection driver and will be freed by
* pn_connection_driver_destroy()
@@ -114,7 +113,7 @@
PN_EXTERN int pn_connection_driver_bind(pn_connection_driver_t *d);
/**
- * Unbind, release and free #connection and #transport. Set all pointers to
+ * Unbind, release and free the connection and transport. Set all pointers to
* NULL. Does not free the @ref pn_connection_driver_t struct itself.
*/
PN_EXTERN void pn_connection_driver_destroy(pn_connection_driver_t *);
@@ -191,7 +190,7 @@
PN_EXTERN bool pn_connection_driver_has_event(pn_connection_driver_t *);
/**
- * Return true if the the engine is closed for reading and writing and there are
+ * Return true if the the driver is closed for reading and writing and there are
* no more events.
*
* Call pn_connection_driver_free() to free all related memory.
diff --git a/proton-c/include/proton/listener.h b/proton-c/include/proton/listener.h
index 5e60649..4244e69 100644
--- a/proton-c/include/proton/listener.h
+++ b/proton-c/include/proton/listener.h
@@ -29,7 +29,7 @@
/**
* @file
*
- * Listener API for the proton @proactor
+ * Listener API for the proton @ref proactor
*
* @defgroup listener Listener
* @ingroup proactor
diff --git a/proton-c/include/proton/proactor.h b/proton-c/include/proton/proactor.h
index 9d39c9c..8a2680b 100644
--- a/proton-c/include/proton/proactor.h
+++ b/proton-c/include/proton/proactor.h
@@ -39,9 +39,9 @@
*
* **Experimental**: Proactor API for portable, multi-threaded, asynchronous applications.
*
- * The proactor establishes and listens for connections. It creates
- * the @ref transport that sends and receives data over the network and
- * delivers @ref event to application threads for handling.
+ * The proactor associates a @ref connection with a @ref transport, either
+ * by making an outgoing connection or accepting an incoming one.
+ * It delivers @ref event "events" to application threads for handling.
*
* **Multi-threading**:
* The @ref proactor is thread-safe, but the @ref engine is not. The proactor
@@ -53,7 +53,7 @@
*/
/**
- * The proactor.
+ * The proactor, see pn_proactor()
*/
typedef struct pn_proactor_t pn_proactor_t;
@@ -71,9 +71,9 @@
* Connect connection to host/port. Connection and transport events will be
* returned by pn_proactor_wait()
*
- * @param[in] connection the proactor takes ownership do not free.
- * @param[in] host the address to listen on
- * @param[in] port the port to connect to
+ * @param[in] connection the proactor takes ownership, do not free
+ * @param[in] host address to connect on
+ * @param[in] port port to connect to
*
* @return error on immediate error, e.g. an allocation failure.
* Other errors are indicated by connection or transport events via pn_proactor_wait()
@@ -84,35 +84,40 @@
* Start listening with listener.
* pn_proactor_wait() will return a PN_LISTENER_ACCEPT event when a connection can be accepted.
*
- * @param[in] listener proactor takes ownership of listener, do not free.
- * @param[in] host the address to listen on
- * @param[in] port the port to listen on
+ * @param[in] listener proactor takes ownership of listener, do not free
+ * @param[in] host address to listen on
+ * @param[in] port port to listen on
+ * @param[in] backlog number of connection requests to queue
*
* @return error on immediate error, e.g. an allocation failure.
* Other errors are indicated by pn_listener_condition() on the PN_LISTENER_CLOSE event.
*/
-int pn_proactor_listen(pn_proactor_t *p, pn_listener_t *listener, const char *host, const char *port, int backlog);
+int pn_proactor_listen(pn_proactor_t *, pn_listener_t *listener, const char *host, const char *port, int backlog);
/**
- * Wait for events to handle. Call pn_proactor_done() after handling events.
+ * Wait for events to handle.
*
- * Thread safe: pn_proactor_wait() can be called concurrently, but the events in
- * the returned ::pn_event_batch_t must be handled sequentially.
+ * Handle events in the returned batch by calling pn_event_batch_next() until it
+ * returns NULL. You must call pn_proactor_done() to when you are finished.
*
- * The proactor always returns events that must be handled sequentially in the
- * same batch or sequentially in a later batch after pn_proactor_done(). Any
- * events returned concurrently by pn_proactor_wait() are safe to handle
- * concurrently.
+ * If you call pn_proactor_done() before finishing the batch, the remaining
+ * events will be returned again by another call pn_proactor_wait(). This is
+ * less efficient, but allows you to handle part of a batch and then hand off
+ * the rest to another thread.
+ *
+ * Thread safe: can be called concurrently. Events in a single batch must be
+ * handled in sequence, but batches returned by separate calls to
+ * pn_proactor_wait() can be handled concurrently.
*/
pn_event_batch_t *pn_proactor_wait(pn_proactor_t* d);
/**
* Call when done handling events.
*
- * It is generally most efficient to handle the entire batch in the thread
- * that calls pn_proactor_wait(), then call pn_proactor_done(). If you call
- * pn_proactor_done() earlier, the remaining events will be returned again by
- * pn_proactor_wait(), possibly to another thread.
+ * Must be called exactly once to match each call to pn_proactor_wait().
+ *
+ * Thread safe: may be called from any thread provided the exactly once rules is
+ * respected.
*/
void pn_proactor_done(pn_proactor_t* d, pn_event_batch_t *events);
@@ -145,17 +150,17 @@
void pn_connection_wake(pn_connection_t *c);
/**
- * The proactor that created the connection.
+ * Return the proactor associated with a connection or null
*/
pn_proactor_t *pn_connection_proactor(pn_connection_t *c);
/**
- * Get the proactor that created the event or NULL.
+ * Return the proactor associated with an event or NULL.
*/
pn_proactor_t *pn_event_proactor(pn_event_t *);
/**
- * Get the listener for the event or NULL.
+ * Return the listener associated with an event or NULL.
*/
pn_listener_t *pn_event_listener(pn_event_t *);
diff --git a/proton-c/include/proton/selectable.h b/proton-c/include/proton/selectable.h
index fbf3823..5eff58d 100644
--- a/proton-c/include/proton/selectable.h
+++ b/proton-c/include/proton/selectable.h
@@ -51,11 +51,11 @@
* pipe version is uni-directional. The network socket version is
* bi-directional. Both are non-blocking.
*
- * pn_socket_t handles from ::pn_pipe() may only be used with
- * ::pn_read(), ::pn_write(), ::pn_close() and pn_selector_select().
+ * pn_socket_t handles from pn_pipe() may only be used with
+ * pn_read(), pn_write(), pn_close() and pn_selector_select().
*
- * pn_socket_t handles from ::pn_listen(), ::pn_accept() and
- * ::pn_connect() must perform further IO using Proton functions.
+ * pn_socket_t handles from pn_listen(), pn_accept() and
+ * pn_connect() must perform further IO using Proton functions.
* Mixing Proton io.h functions with native IO functions on the same
* handles will result in undefined behavior.
*
