PROTON-1109: Improve C++ binding documentation

 - Update the overview and tutorial; this is Alan's work
 - Add lots of new API documentation
 - Correct broken links
 - Hide elements of the API that are not yet settled
 - Configure doxygen for less cluttered output
 - Clean up the header files (all one style)
 - Adjust the formatting of some of the examples

examples/cpp/README.hpp

@@ -1,72 +1,74 @@
 // Examples overview.
 //
 // For a better overview, see the tutorial in the generated documentation.
+//
 // In your build directory do:
+//
 //     make docs-cpp
-// then open proton-c/bindings/cpp/docs/html/tutorial.html in your browser.
 //
+// then open proton-c/bindings/cpp/docs/html/tutorial.html in your browser.
 
 // DEVELOPER NOTE: if you are adding or modifying examples you should keep this
 // file and ../proton-c/bindings/cpp/docs/tutorial.hpp up to date.
 
-/** \example helloworld.cpp
+/** @example helloworld.cpp
 
-Basic example that connects to an intermediary on 127.0.0.1:5672,
-establishes a subscription from the 'examples' nodeu on that
-intermediary, then creates a sending link to the same node and sends
-one message. On receving the message back via the subcription, the
-connection is closed.
+Connects to a broker on 127.0.0.1:5672, establishes a subscription
+from the 'examples' node, and creates a sending link to the same
+node. Sends one message and receives it back.
 
 */
 
-/** \example helloworld_direct.cpp
+/** @example helloworld_direct.cpp
 
-A variant of the basic helloworld example, that does not use an
-intermediary, but listens for incoming connections itself. It
-establishes a connection to itself with a link over which a single
-message is sent. This demonstrates the ease with which a simple daemon
-can be built using the API.
+Variation of helloworld that does not use a broker, but listens for
+incoming connections itself. It establishes a connection to itself
+with a link over which a single message is sent. This demonstrates the
+ease with which a simple daemon an be built using the API.
 
 */
 
-/** \example simple_send.cpp
+/** @example simple_send.cpp
 
 An example of sending a fixed number of messages and tracking their
 (asynchronous) acknowledgement. Messages are sent through the 'examples' node on
 an intermediary accessible on 127.0.0.1:5672.
 
 */
 
-/** \example simple_recv.cpp
+/** @example simple_recv.cpp
 
 Subscribes to the 'examples' node on an intermediary accessible
 on 127.0.0.1:5672. Simply prints out the body of received messages.
 
 */
 
-/** \example direct_send.cpp
+/** @example direct_send.cpp
 
 Accepts an incoming connection and then sends like `simple_send`.  You can
 connect directly to `direct_send` *without* a broker using \ref simple_recv.cpp.
 Make sure to stop the broker first or use a different port for `direct_send`.
 
 */
 
-/** \example direct_recv.cpp
+/** @example direct_recv.cpp
 
 Accepts an incoming connection and then receives like `simple_recv`.  You can
 connect directly to `direct_recv` *without* a broker using \ref simple_send.cpp.
 Make sure to stop the broker first or use a different port for `direct_recv`.
 
 */
 
-/** \example encode_decode.cpp
+/// @cond INTERNAL
+/// XXX change namespaces
+/** @example encode_decode.cpp
 
 Shows how C++ data types can be converted to and from AMQP types.
 
 */
+/// @endcond
 
-/** \example client.cpp
+/** @example client.cpp
 
 The client part of a request-response example. Sends requests and
 prints out responses. Requires an intermediary that supports the AMQP
@@ -75,17 +77,17 @@ are sent through the 'examples' node.
 
 */
 
-/** \example server.cpp
+/** @example server.cpp
 
 The server part of a request-response example, that receives requests
 via the examples node, converts the body to uppercase and sends the
 result back to the indicated reply address.
 
 */
 
-/** \example server_direct.cpp
+/** @example server_direct.cpp
 
-A variant of the server part of a request-response example, that
+A variant of the server part of a request-response example that
 accepts incoming connections and does not need an intermediary. Much
 like the original server, it receives incoming requests, converts the
 body to uppercase and sends the result back to the indicated reply
@@ -94,23 +96,98 @@ alternatives.
 
 */
 
-/** \example broker.hpp
+/** @example broker.hpp
 
 Common logic for a simple "mini broker" that creates creates queues
 automatically when a client tries to send or subscribe. This file contains
 the `queue` class that queues messages and the `broker_handler` class
 that manages queues and links and transfers messages to/from clients.
 
-There are several broker programs all using the same logic but illustrating
-different ways to run a server application.
+Examples \ref broker.cpp and \ref engine/broker.cpp use this same
+broker logic but show different ways to run it in a server application.
+
+*/
+
+/** @example broker.cpp
+
+A simple, single-threaded broker using the `proton::container`. You can use this
+to run other examples that reqiure an intermediary, or you can use any AMQP 1.0
+broker. This broker creates queues automatically when a client tries to send or
+subscribe.
+
+Uses the broker logic from \ref broker.hpp, the same logic as the
+`proton::connection_engine` broker example \ref engine/broker.cpp.
+
+*/
+
+//////////////// connection_engine examples.
+
+/** \example engine/helloworld.cpp
+
+`proton::connection_engine` example to send a "Hello World" message to
+itself. Compare with the corresponding `proton::container` example \ref
+helloworld.cpp.
+
+*/
+
+/** \example engine/simple_send.cpp
+
+`proton::connection_engine` example of sending a fixed number of messages and
+tracking their (asynchronous) acknowledgement. Messages are sent through the
+'examples' node on an intermediary accessible on 127.0.0.1:5672.
 
 */
 
-/** \example broker.cpp
+/** \example engine/simple_recv.cpp
+
+`proton::connection_engine` example that subscribes to the 'examples' node and prints
+ the body of received messages.
+
+*/
+
+/** \example engine/direct_send.cpp
+
+`proton::connection_engine` example accepts an incoming connection and then
+sends like `simple_send`.  You can connect directly to `direct_send` *without* a
+broker using \ref simple_recv.cpp.  Make sure to stop the broker first or use a
+different port for `direct_send`.
+
+*/
+
+/** \example engine/direct_recv.cpp
+
+`proton::connection_engine` example accepts an incoming connection and then
+receives like `simple_recv`.  You can connect directly to `direct_recv`
+*without* a broker using \ref simple_send.cpp.  Make sure to stop the broker
+first or use a different port for `direct_recv`.
+
+*/
+
+/** \example engine/client.cpp
+
+`proton::connection_engine` client for request-response example. Sends requests and
+prints out responses. Requires an intermediary that supports the AMQP 1.0
+dynamic nodes on which the responses are received. The requests are sent through
+the 'examples' node.
+
+*/
+
+/** \example engine/server.cpp
+
+`proton::connection_engine` server for request-response example, that receives
+requests via the examples node, converts the body to uppercase and sends the
+result back to the indicated reply address.
+
+*/
+
+/** \example engine/broker.cpp
 
 A simple, single-threaded broker using the `proton::container`. You can use this
 to run other examples that reqiure an intermediary, or you can use any AMQP 1.0
 broker. This broker creates queues automatically when a client tries to send or
 subscribe.
 
+Uses the broker logic from \ref broker.hpp, the same logic as the
+proton::container` broker example \ref broker.cpp.
+
 */

examples/cpp/broker.cpp

@@ -39,7 +39,6 @@ class broker {
     proton::handler& handler() { return handler_; }
 
   private:
-
     class my_handler : public broker_handler {
       public:
         my_handler(const proton::url& u, queues& qs) : broker_handler(qs), url_(u) {}
@@ -59,19 +58,23 @@ class broker {
 };
 
 int main(int argc, char **argv) {
-    // Command line options
     proton::url url("0.0.0.0");
     options opts(argc, argv);
+
     opts.add_value(url, 'a', "address", "listen on URL", "URL");
+
     try {
         opts.parse();
+
         broker b(url);
         proton::container(b.handler()).run();
+
         return 0;
     } catch (const bad_option& e) {
         std::cout << opts << std::endl << e.what() << std::endl;
     } catch (const std::exception& e) {
         std::cerr << e.what() << std::endl;
     }
+
     return 1;
 }