Merge pull request #122 from xaqq/doxygen

Documentation improvement + switch to 4.1.2

CHANGES.md

@@ -1,6 +1,14 @@
 Development
 ===========
 
+
+
+Version 4.1.2
+=============
+
+* Fix a compilation bug (#119)
+* Improve documentation
+
 Version 4.1.1
 =============
 

Doxyfile

@@ -32,13 +32,13 @@ PROJECT_NAME           = zmqpp
 # This could be handy for archiving the generated documentation or
 # if some version control system is used.
 
-PROJECT_NUMBER         = 4.1.1
+PROJECT_NUMBER         = 4.1.2
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer
 # a quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          = "C++ bindings for 0mq"
+PROJECT_BRIEF          = "C++ bindings for 0mq (libzmq)"
 
 # With the PROJECT_LOGO tag one can specify an logo or icon that is
 # included in the documentation. The maximum height of the logo should not

Makefile

@@ -27,7 +27,7 @@ AR       = ar
 LIBRARY_NAME     = zmqpp
 VERSION_MAJOR    = 4
 VERSION_MINOR    = 1
-VERSION_REVISION = 1
+VERSION_REVISION = 2
 
 #
 # Paths

src/mainpage.md

@@ -0,0 +1,43 @@
+@mainpage
+
+Introduction
+------------
+
+zmqpp is a "high-level" C++ binding for 0mq/zmq. The "high-level" term is used in
+comparison to [cppzmq](https://github.com/zeromq/cppzmq) which is somewhat a raw wrapper
+around the [libzmq](https://github.com/zeromq/libzmq) C interface.
+
+The library is documented and has a nice test suite. This doesn't mean that the library is bug
+free or that the test suite is 100% complete.
+
+The development takes places in this [GitHub repository](http://github.com/zeromq/zmqpp).
+
+
+Features
+---------
+
+Basic features:
+
++ zmqpp provides most feature from libzmq in a C++ style API.
++ It supports multiple version of [libzmq](https://github.com/zeromq/libzmq).
+
+Being built on top of libzmq, and being a higher-level binding, zmqpp provides some
+additional features:
+
++ [Reactor](@ref zmqpp::reactor) pattern.
++ [Actor](@ref zmqpp::actor) pattern.
++ Support for ZAP.
+
+
+Examples
+--------
+
+zmqpp comes a few examples. These can be found [here](https://github.com/zeromq/zmqpp/tree/develop/examples).
+
+Reading the documentation is a good way to start learning about zmqpp.
+The most important classes that you will likely use are thoses:
+
++ [Context](@ref zmqpp::context).
++ [Socket](@ref zmqpp::socket).
++ [Message](@ref zmqpp::message).
++ And either a [Poller](@ref zmqpp::poller) or a [Reactor](@ref zmqpp::reactor).

src/zmqpp/auth.hpp

@@ -35,7 +35,7 @@
 namespace zmqpp
 {
 
-/*!
+/**
  * auth - authentication for ZeroMQ security mechanisms
  * 
  * An auth actor takes over authentication for all incoming connections in
@@ -46,21 +46,21 @@ namespace zmqpp
 class auth 
 {
 public:
-	/*!
+	/**
 	 * Constructor. A auth actor takes over authentication for all incoming connections in
 	 * its context. You can whitelist or blacklist peers based on IP address,
 	 * and define policies for securing PLAIN, CURVE, and GSSAPI connections.
 	 *
 	 */
 	auth(context& ctx);
 
-	/*!
+	/**
 	 * Destructor.
 	 *
 	 */
     	~auth();
 
-	/*!
+	/**
 	 * Allow (whitelist) a single IP address. For NULL, all clients from this
 	 * address will be accepted. For PLAIN and CURVE, they will be allowed to
 	 * continue with authentication. You can call this method multiple times
@@ -70,7 +70,7 @@ class auth
 	 */
     	void allow(const std::string &address);
 
-    	/*!
+    	/**
 	 * Deny (blacklist) a single IP address. For all security mechanisms, this
 	 * rejects the connection without any further authentication. Use either a
      	 * whitelist, or a blacklist, not not both. If you define both a whitelist
@@ -79,68 +79,68 @@ class auth
 	 */
     	void deny(const std::string &address);
 
-    	/*!
+    	/**
 	 * Configure a ZAP domain. To cover all domains, use "*".
 	 */
     	void configure_domain(const std::string &domain);
 
-    	/*!
+    	/**
 	 * Configure PLAIN authentication. PLAIN authentication uses a plain-text 
 	 * username and password.
 	 *
 	 */
     	void configure_plain(const std::string &username, const std::string &password);
 
-    	/*!
+    	/**
 	 * Configure CURVE authentication. CURVE authentication uses client public keys. 
 	 * This method can be called multiple times. To cover all domains, use "*". 
 	 * To allow all client keys without checking, specify CURVE_ALLOW_ANY for the client_public_key.
 	 *
 	 */
     	void configure_curve(const std::string &client_public_key);
 
-    	/*!
+    	/**
 	 * Configure GSSAPI authentication. GSSAPI authentication uses an underlying 
 	 * mechanism (usually Kerberos) to establish a secure context and perform mutual 
 	 * authentication.
 	 *
 	 */
     	void configure_gssapi();
 
-    	/*!
+    	/**
 	 * Enable verbose tracing of commands and activity.
 	 *
 	 */
     	void set_verbose(bool verbose);
 
 private:
-	/*!
+	/**
 	 * Handle an authentication command from calling application.
 	 *
 	 */
     	void handle_command(socket& pipe);
 
-	/*!
+	/**
 	 * Handle a PLAIN authentication request from libzmq core
 	 *
 	 * @param user_id store the user as the User-Id.
 	 */
     	bool authenticate_plain(zap_request& request, std::string &user_id);
 
-	/*!
+	/**
 	 * Handle a CURVE authentication request from libzmq core
 	 *
 	 * @param user_id store the public key (z85 encoded) as the User-Id.
 	 */
     	bool authenticate_curve(zap_request& request, std::string &user_id);
 
-    	/*!
+    	/**
 	 * Handle a GSSAPI authentication request from libzmq core
 	 *
 	 */
     	bool authenticate_gssapi(zap_request& request);
 
-    	/*!
+    	/**
      	 * Authentication.
      	 *
      	 */

src/zmqpp/context.hpp

@@ -30,7 +30,7 @@
 namespace zmqpp
 {
 
-/*!
+/**
  * The context class represents internal zmq context and io threads.
  *
  * By default the context class will create one thread, however this can be
@@ -48,7 +48,7 @@ class context
 public:
 
 #if (ZMQ_VERSION_MAJOR < 3) || ((ZMQ_VERSION_MAJOR == 3) && (ZMQ_VERSION_MINOR < 2))
-	/*!
+	/**
 	 * Initialise the 0mq context.
 	 *
 	 * If only inproc is used then the context may be created with zero threads.
@@ -62,7 +62,7 @@ class context
 	 */
 	context(int const& threads = 1)
 #else
-	/*!
+	/**
 	 * Initialise the 0mq context.
 	 *
 	 * The context is thread safe an may be used anywhere in your application,
@@ -85,7 +85,7 @@ class context
 		}
 	}
 
-	/*!
+	/**
 	 * Closes the 0mq context.
 	 *
 	 * Any blocking calls other than a socket close will return with an error.
@@ -101,7 +101,7 @@ class context
 		}
 	}
 
-	/*!
+	/**
 	 * Move supporting constructor.
 	 *
 	 * Allows zero-copy move semantics to be used with this class.
@@ -114,7 +114,7 @@ class context
 		source._context = nullptr;
 	}
 
-	/*!
+	/**
 	 * Move supporting operator.
 	 *
 	 * Allows zero-copy move semantics to be used with this class.
@@ -127,7 +127,7 @@ class context
 		return *this;
 	}
 
-	/*!
+	/**
 	 * Terminate the current context.
 	 *
 	 * Any blocking calls other than a socket close will return with an error.
@@ -138,15 +138,15 @@ class context
 	void terminate();
 
 #if (ZMQ_VERSION_MAJOR > 3) || ((ZMQ_VERSION_MAJOR == 3) && (ZMQ_VERSION_MINOR >= 2))
-	/*!
+	/**
 	 * Set the value of an option in the underlaying zmq context.
 	 *
 	 * \param option a valid ::context_option
 	 * \param value to set the option to
 	 */
 	void set(context_option const option, int const value);
 
-	/*!
+	/**
 	 * Get a context option from the underlaying zmq context.
 	 *
 	 * \param option a valid ::context_option
@@ -155,7 +155,7 @@ class context
 	int get(context_option const option);
 #endif
 
-	/*!
+	/**
 	 * Validity checking of the context
 	 *
 	 * Checks if the underlying 0mq context for this instance is valid.
@@ -170,7 +170,7 @@ class context
 		return nullptr != _context;
 	}
 
-	/*!
+	/**
 	 * Access to the raw 0mq context
 	 *
 	 * \return void pointer to the underlying 0mq context.

src/zmqpp/curve.hpp

@@ -20,9 +20,16 @@
 #include <string>
 #include <zmq.h>
 
-namespace zmqpp { namespace curve
+namespace zmqpp {
+/**
+* ZMQ curve facilities.
+*/
+namespace curve
 {
 
+/**
+* A pair of public and private key.
+*/
 struct keypair
 {
 	std::string public_key;

src/zmqpp/exception.hpp

@@ -27,7 +27,7 @@ namespace zmqpp
 
 /** \todo Have a larger variety of exceptions with better state debug information */
 
-/*!
+/**
  * Represents the base zmqpp exception.
  *
  * All zmqpp runtime exceptions are children of this class.
@@ -40,7 +40,7 @@ namespace zmqpp
 class exception : public std::runtime_error
 {
 public:
-	/*!
+	/**
 	 * Standard exception constructor.
 	 *
 	 * \param message a string representing the error message.
@@ -50,7 +50,7 @@ class exception : public std::runtime_error
 	{ }
 };
 
-/*!
+/**
  * Represents an attempt to use an invalid object.
  *
  * Objects may be invalid initially or after a shutdown or close.
@@ -90,7 +90,7 @@ class invalid_instance : public exception
     }
   };
 
-/*!
+/**
  * Represents internal zmq errors.
  *
  * Any error response from the zmq bindings will be wrapped in this error.
@@ -100,15 +100,15 @@ class invalid_instance : public exception
 class zmq_internal_exception : public exception
 {
 public:
-	/*!
+	/**
 	 * Uses the zmq functions to pull out error messages and numbers.
 	 */
 	zmq_internal_exception()
 		: exception(zmq_strerror(zmq_errno()))
 		, _error(zmq_errno())
 	{ }
 
-	/*!
+	/**
 	 * Retrieve the zmq error number associated with this exception.
 	 * \return zmq error number
 	 */

src/zmqpp/message.hpp

@@ -33,7 +33,7 @@
 namespace zmqpp
 {
 
-/*!
+/**
  * \brief a zmq message with optional multipart support
  *
  * A zmq message is made up of one or more parts which are sent together to
@@ -43,7 +43,7 @@ namespace zmqpp
 class message
 {
 public:
-	/*!
+	/**
 	 * \brief callback to release user allocated data.
 	 *
 	 * The release function will be called on any void* moved part.