update documentation and code style

websocketpp/connection.hpp

@@ -47,27 +47,125 @@
 
 namespace websocketpp {
 
+/// The type and function signature of an open handler
+/**
+ * The open handler is called once for every successful WebSocket connection 
+ * attempt. Either the fail handler or the open handler will be called for each
+ * WebSocket connection attempt. HTTP Connections that did not attempt to 
+ * upgrade the connection to the WebSocket protocol will trigger the http 
+ * handler instead of fail/open.
+ */
 typedef lib::function<void(connection_hdl)> open_handler;
+
+/// The type and function signature of a close handler
+/**
+ * The close handler is called once for every successfully established 
+ * connection after it is no longer capable of sending or receiving new messages
+ *
+ * The close handler will be called exactly once for every connection for which
+ * the open handler was called.
+ */
 typedef lib::function<void(connection_hdl)> close_handler;
+
+/// The type and function signature of a fail handler
+/**
+ * The fail handler is called once for every unsuccessful WebSocket connection 
+ * attempt. Either the fail handler or the open handler will be called for each
+ * WebSocket connection attempt. HTTP Connections that did not attempt to 
+ * upgrade the connection to the WebSocket protocol will trigger the http 
+ * handler instead of fail/open.
+ */
 typedef lib::function<void(connection_hdl)> fail_handler;
 
+/// The type and function signature of an interrupt handler
+/**
+ * The interrupt handler is called when a connection receives an interrupt 
+ * request from the application. Interrupts allow the application to trigger a
+ * handler to be run in the absense of a WebSocket level handler trigger (like
+ * a new message).
+ *
+ * This is typically used by another application thread to schedule some tasks
+ * that can only be run from within the handler chain for thread safety reasons.
+ */
 typedef lib::function<void(connection_hdl)> interrupt_handler;
 
-typedef lib::function<void(connection_hdl)> handshake_init_handler;
-
+/// The type and function signature of a ping handler
+/**
+ * The ping handler is called when the connection receives a WebSocket ping
+ * control frame. The string argument contains the ping payload. The payload is
+ * a binary string up to 126 bytes in length. The ping handler returns a bool, 
+ * true if a pong response should be sent, false if the pong response should be
+ * suppressed.
+ */
 typedef lib::function<bool(connection_hdl,std::string)> ping_handler;
+
+/// The type and function signature of a pong handler
+/**
+ * The pong handler is called when the connection receives a WebSocket pong
+ * control frame. The string argument contains the pong payload. The payload is
+ * a binary string up to 126 bytes in length.
+ */
 typedef lib::function<void(connection_hdl,std::string)> pong_handler;
+
+/// The type and function signature of a pong timeout handler
+/**
+ * The pong timeout handler is called when a ping goes unanswered by a pong for
+ * longer than the locally specified timeout period.
+ */
 typedef lib::function<void(connection_hdl,std::string)> pong_timeout_handler;
 
+/// The type and function signature of a validate handler
+/**
+ * The validate handler is called after a WebSocket handshake has been received
+ * and processed but before it has been accepted. This gives the application a 
+ * chance to impliment connection details specific policies for accepting 
+ * connections and the ability to negotiate extensions and subprotocols.
+ * 
+ * The validate handler return value indicates whether or not the connection 
+ * should be accepted. Additional methods may be called during the function to
+ * set response headers, set HTTP return/error codes, etc.
+ */
 typedef lib::function<bool(connection_hdl)> validate_handler;
+
+/// The type and function signature of a http handler
+/**
+ * The http handler is called when an HTTP connection is made that does not
+ * attempt to upgrade the connection to the WebSocket protocol. This allows
+ * WebSocket++ servers to respond to these requests with regular HTTP responses.
+ * 
+ * This can be used to deliver error pages & dashboards and to deliver static 
+ * files such as the base HTML & JavaScript for an otherwise single page 
+ * WebSocket application.
+ *
+ * Note: WebSocket++ is designed to be a high performance WebSocket server. It
+ * is not tuned to provide a full featured, high performance, HTTP web server
+ * solution. The HTTP handler is appropriate only for low volume HTTP traffic.
+ * If you expect to serve high volumes of HTTP traffic a dedicated HTTP web 
+ * server is strongly recommended.
+ *
+ * The default HTTP handler will return a 426 Upgrade Required error. Custom
+ * handlers may override the response status code to deliver any type of 
+ * response.
+ */
 typedef lib::function<void(connection_hdl)> http_handler;
 
 // constants related to the default WebSocket protocol versions available
 #ifdef _WEBSOCKETPP_INITIALIZER_LISTS_ // simplified C++11 version
-    static const std::vector<int>   VERSIONS_SUPPORTED = {0,7,8,13};
+    /// Container that stores the list of protocol versions supported
+    /**
+     * @todo Move this to configs to allow compile/runtime disabling or enabling
+     * of protocol versions
+     */
+    static std::vector<int> const versions_supported = {0,7,8,13};
 #else
-    static const int HELPER[] = {0,7,8,13};
-    static const std::vector<int>   VERSIONS_SUPPORTED(HELPER,HELPER+4);
+    /// Helper array to get around lack of initializer lists pre C++11
+    static int const helper[] = {0,7,8,13};
+    /// Container that stores the list of protocol versions supported
+    /**
+     * @todo Move this to configs to allow compile/runtime disabling or enabling
+     * of protocol versions
+     */
+    static std::vector<int> const versions_supported(helper,helper+4);
 #endif
 
 namespace session {

websocketpp/endpoint.hpp

@@ -88,8 +88,8 @@ public:
     typedef lib::shared_ptr<connection_weak_ptr> hdl_type;
 
     explicit endpoint(bool is_server)
-      : m_alog(config::alog_level,&std::cout)
-      , m_elog(config::elog_level,&std::cerr)
+      : m_alog(config::alog_level, &std::cout)
+      , m_elog(config::elog_level, &std::cerr)
       , m_user_agent(::websocketpp::user_agent)
       , m_is_server(is_server)
     {
@@ -106,7 +106,7 @@ public:
      * Returns the user agent string that this endpoint will use when creating
      * new connections. 
      *
-     * The default value for this version is WebSocket++/0.3.0dev
+     * The default value for this version is stored in websocketpp::user_agent
      *
      * @return The user agent string.
      */ 
@@ -122,11 +122,11 @@ public:
      *
      * For best results set this before accepting or opening connections.
      *
-     * The default value for this version is WebSocket++/0.3.0dev
+     * The default value for this version is stored in websocketpp::user_agent
      *
      * @param ua The string to set the user agent to.
      */ 
-    void set_user_agent(const std::string& ua) {
+    void set_user_agent(std::string const & ua) {
         scoped_lock_type guard(m_mutex);
         m_user_agent = ua;
     }
@@ -189,21 +189,17 @@ public:
     
     /// Get reference to access logger
     /**
-     * TODO
-     * 
      * @return A reference to the access logger
      */
-    alog_type& get_alog() {
+    alog_type & get_alog() {
         return m_alog;
     }
     
     /// Get reference to error logger
     /**
-     * TODO
-     * 
      * @return A reference to the error logger
      */
-    elog_type& get_elog() {
+    elog_type & get_elog() {
         return m_elog;
     }
     

websocketpp/impl/connection_impl.hpp

@@ -962,7 +962,7 @@ bool connection<config>::initialize_processor() {
     std::stringstream ss;
     std::string sep = "";
     std::vector<int>::const_iterator it;
-    for (it = VERSIONS_SUPPORTED.begin(); it != VERSIONS_SUPPORTED.end(); it++)
+    for (it = versions_supported.begin(); it != versions_supported.end(); it++)
     {
         ss << sep << *it;
         sep = ",";
@@ -1625,7 +1625,7 @@ void connection<config>::atomic_state_check(istate_type req,
 template <typename config>
 const std::vector<int>& connection<config>::get_supported_versions() const
 {
-    return VERSIONS_SUPPORTED;
+    return versions_supported;
 }
 
 template <typename config>

websocketpp/transport/asio/security/base.hpp

@@ -41,7 +41,7 @@
 
 // Interface that sockets/security policies must implement
 
-/**
+/*
  * Endpoint Interface
  *
  * bool is_secure() const;
@@ -55,10 +55,10 @@
  */
 
 
-/// Connection
-/// TODO
-/// pre_init(init_handler);
-/// post_init(init_handler);
+// Connection
+// TODO
+// pre_init(init_handler);
+// post_init(init_handler);
 
 namespace websocketpp {
 namespace transport {

websocketpp/uri.hpp

@@ -38,8 +38,6 @@
 
 namespace websocketpp {
 
-// WebSocket URI only (not http/etc) 
-
 class uri_exception : public std::exception {
 public: 
     uri_exception(const std::string& msg) : m_msg(msg) {}
@@ -53,10 +51,21 @@ private:
 };
 
 // TODO: figure out why this fixes horrible linking errors.
-static const uint16_t URI_DEFAULT_PORT = 80;
-static const uint16_t uri_default_port = 80;
-static const uint16_t URI_DEFAULT_SECURE_PORT = 443;
-static const uint16_t uri_default_secure_port = 443;
+
+/// Default port for ws:// [deprecated]
+/**
+ * @deprecated Use uri_default_port instead. Will be removed before 1.0.0
+ */
+static uint16_t const URI_DEFAULT_PORT = 80;
+/// Default port for ws:// 
+static uint16_t const uri_default_port = 80;
+/// Default port for wss:// [deprecated]
+/**
+ * @deprecated Use uri_default_secure_port instead. Will be removed before 1.0.0
+ */
+static uint16_t const URI_DEFAULT_SECURE_PORT = 443;
+/// Default port for wss:// 
+static uint16_t const uri_default_secure_port = 443;
 
 class uri {
 public:

websocketpp/utilities.hpp

@@ -32,6 +32,7 @@
 #include <websocketpp/common/stdint.hpp>
 
 namespace websocketpp {
+/// Generic non-websocket specific utility functions and data structures
 namespace utility {
 
 /// Helper functor for case insensitive find

websocketpp/version.hpp

@@ -28,6 +28,7 @@
 #ifndef WEBSOCKETPP_VERSION_HPP
 #define WEBSOCKETPP_VERSION_HPP
 
+/// Namespace for the WebSocket++ project
 namespace websocketpp {
 
 /*
@@ -39,11 +40,20 @@ namespace websocketpp {
  - CMakeLists.txt
 */
 
+/// Library major version number
 static int const major_version = 0;
+/// Library minor version number
 static int const minor_version = 3;
+/// Library patch version number
 static int const patch_version = 0;
+/// Library pre-release flag
+/**
+ * This is a textual flag indicating the type and number for pre-release 
+ * versions (dev, alpha, beta, rc). This will be blank for release versions.
+ */
 static char const prerelease_flag[] = "alpha2";
 
+/// Default user agent string
 static char const user_agent[] = "WebSocket++/0.3.0-alpha2";
 
 } // namespace websocketpp