add documentation & normalize code style

websocketpp/common/functional.hpp

@@ -54,7 +54,7 @@ namespace lib {
     using boost::bind;
     using boost::ref;
     namespace placeholders {
-        // TODO: there has got to be a better way than this
+        /// \todo this feels hacky, is there a better way?
         using ::_1;
         using ::_2;
     }

websocketpp/connection.hpp

@@ -399,7 +399,7 @@ public:
      * and then added
      *
      * Errors are returned via an exception
-     * TODO: make exception system_error rather than error_code
+     * \todo make exception system_error rather than error_code
      *
      * This method invokes the m_write_lock mutex
      *
@@ -871,7 +871,7 @@ public:
     
     /// Checks if there are frames in the send queue and if there are sends one
     /**
-     * TODO: unit tests
+     * \todo unit tests
      *
      * This method locks the m_write_lock mutex
      */
@@ -879,7 +879,7 @@ public:
     
     /// Process the results of a frame write operation and start the next write
     /**
-     * TODO: unit tests
+     * \todo unit tests
      *
      * This method locks the m_write_lock mutex
      *
@@ -1011,7 +1011,7 @@ private:
      *
      * Must be called while holding m_write_lock
      *
-     * TODO: unit tests
+     * \todo unit tests
      *
      * @param msg The message to push
      */
@@ -1024,7 +1024,7 @@ private:
      *
      * Must be called while holding m_write_lock
      *
-     * TODO: unit tests
+     * \todo unit tests
      *
      * @return the message_ptr at the front of the queue
      */
@@ -1097,8 +1097,8 @@ private:
     timer_ptr               m_handshake_timer;
     timer_ptr               m_ping_timer;
     
-    // TODO: this is not memory efficient. this value is not used after the
-    // handshake.
+    /// \todo this is not memory efficient. this value is not used after the
+    /// handshake.
     std::string m_handshake_buffer;
     
     /// Pointer to the processor object for this connection

websocketpp/http/impl/parser.hpp

@@ -35,8 +35,16 @@ namespace websocketpp {
 namespace http {
 namespace parser {
 
-inline bool parser::parse_parameter_list(const std::string& in, 
-    parameter_list& out) const
+/// Extract an HTTP parameter list from a string.
+/**
+ * @param [in] in The input string.
+ *
+ * @param [out] out The parameter list to store extracted parameters in.
+ *
+ * @return Whether or not the input was a valid parameter list.
+ */
+inline bool parser::parse_parameter_list(std::string const & in, 
+    parameter_list & out) const
 {
     if (in.size() == 0) {
         return false;
@@ -47,33 +55,48 @@ inline bool parser::parse_parameter_list(const std::string& in,
     return (it == in.begin());
 }
 
-inline bool parser::get_header_as_plist(const std::string& key, 
-    parameter_list& out) const
+/// Extract an HTTP parameter list from a parser header.
+/**
+ * If the header requested doesn't exist or exists and is empty the parameter
+ * list is valid (but empty).
+ *
+ * @param [in] key The name/key of the HTTP header to use as input.
+ *
+ * @param [out] out The parameter list to store extracted parameters in.
+ *
+ * @return Whether or not the input was a valid parameter list.
+ */
+inline bool parser::get_header_as_plist(std::string const & key, 
+    parameter_list & out) const
 {
     header_list::const_iterator it = m_headers.find(key);
     
-    // If this header doesn't exist it is valid
-    if (it == m_headers.end()) {
-        return false;
-    }
-    
-    // If this header exists but is empty it is valid
-    if (it->second.size() == 0) {
+    if (it == m_headers.end() || it->second.size() == 0) {
         return false;
     }
 
     return this->parse_parameter_list(it->second,out);
 }
 
-inline void parser::set_version(const std::string& version) {
-    // TODO: validation?
-    
-    // first four chars == HTTP/
-    
+/// Set HTTP parser Version
+/**
+ * \todo Does this method need any validation?
+ *
+ * @param [in] version The value to set the HTTP version to.
+ */
+inline void parser::set_version(std::string const & version) {
     m_version = version;
 }
-    
-inline const std::string& parser::get_header(const std::string& key) const {
+
+/// Get the value of an HTTP header
+/**
+ * \todo Make this method case insensitive.
+ *
+ * @param [in] key The name/key of the header to get.
+ *
+ * @return The value associated with the given HTTP header key.
+ */
+inline std::string const & parser::get_header(std::string const & key) const {
     header_list::const_iterator h = m_headers.find(key);
     
     if (h == m_headers.end()) {
@@ -82,15 +105,28 @@ inline const std::string& parser::get_header(const std::string& key) const {
         return h->second;
     }
 }
-    
-inline void parser::append_header(const std::string &key,const std::string 
-    &val)
+
+/// Append a value to an existing HTTP header
+/**
+ * This method will set the value of the HTTP header `key` with the indicated 
+ * value. If a header with the name `key` already exists, `val` will be appended
+ * to the existing value.
+ *
+ * \todo Make this method case insensitive.
+ * \todo Should there be any restrictions on which keys are allowed to be set?
+ * \todo Exception free varient
+ *
+ * @param [in] key The name/key of the header to append to.
+ *
+ * @param [in] val The value to append.
+ */
+inline void parser::append_header(std::string const & key, std::string const &
+    val)
 {
     if (std::find_if(key.begin(),key.end(),is_not_token_char) != key.end()) {
         throw exception("Invalid header name",status_code::bad_request);
     }
     
-    // TODO: prevent use of reserved headers?
     if (this->get_header(key) == "") {
         m_headers[key] = val;
     } else {
@@ -98,29 +134,63 @@ inline void parser::append_header(const std::string &key,const std::string
     }
 }
 
-inline void parser::replace_header(const std::string &key,const std::string 
-    &val)
+/// Set a value for an HTTP header, replacing an existing value
+/**
+ * This method will set the value of the HTTP header `key` with the indicated 
+ * value. If a header with the name `key` already exists, `val` will replace the
+ * existing value.
+ *
+ * \todo Make this method case insensitive.
+ * \todo Should there be any restrictions on which keys are allowed to be set?
+ * \todo Exception free varient
+ *
+ * @param [in] key The name/key of the header to append to.
+ *
+ * @param [in] val The value to append.
+ */
+inline void parser::replace_header(std::string const & key, std::string const &
+    val)
 {
     m_headers[key] = val;
 }
 
-inline void parser::remove_header(const std::string &key) {
+/// Remove a header from the parser
+/**
+ * Removes the header entirely from the parser. This is different than setting
+ * the value of the header to blank.
+ *
+ * \todo Make this method case insensitive.
+ *
+ * @param [in] key The name/key of the header to remove.
+ */
+inline void parser::remove_header(std::string const & key) {
     m_headers.erase(key);
 }
 
-inline void parser::set_body(const std::string& value) {
+/// Set HTTP body
+/**
+ * Sets the body of the HTTP object and fills in the appropriate content length
+ * header
+ *
+ * @param [in] value The value to set the body to.
+ */
+inline void parser::set_body(std::string const & value) {
     if (value.size() == 0) {
         remove_header("Content-Length");
         m_body = "";
         return;
     }
     
-    std::stringstream foo;
-    foo << value.size();
-    replace_header("Content-Length", foo.str());
+    std::stringstream len;
+    len << value.size();
+    replace_header("Content-Length", len.str());
     m_body = value;
 }
 
+/// Parse headers from an istream
+/**
+ * @param [in] s The istream to extract headers from.
+ */
 inline bool parser::parse_headers(std::istream& s) {
     std::string header;
     std::string::size_type end;
@@ -143,6 +213,13 @@ inline bool parser::parse_headers(std::istream& s) {
     return true;
 }
 
+/// Generate and return the HTTP headers as a string
+/**
+ * Each headers will be followed by the \r\n sequence including the last one.
+ * A second \r\n sequence (blank header) is not appended by this method
+ *
+ * @return The HTTP headers as a string.
+ */
 inline std::string parser::raw_headers() const {
     std::stringstream raw;
     
@@ -154,6 +231,13 @@ inline std::string parser::raw_headers() const {
     return raw.str();
 }
 
+/// Process a header
+/**
+ *
+ * \todo Update this method to be exception free.
+ *
+ * @param [in] s The istream to extract headers from.
+ */
 inline void parser::process_header(std::string::iterator begin, 
     std::string::iterator end)
 {

websocketpp/http/impl/request.hpp

@@ -148,7 +148,14 @@ inline void request::set_method(const std::string& method) {
 
     m_method = method;
 }
-    
+
+/// Set HTTP body
+/**
+ * Sets the body of the HTTP object and fills in the appropriate content length
+ * header
+ *
+ * @param value The value to set the body to.
+ */
 inline void request::set_uri(const std::string& uri) {
     // TODO: validation?
     m_uri = uri;