Improved comments on public functions and variables as suggested in o…

…penjournals/joss-reviews#1592 (comment)

client_http.hpp

@@ -15,6 +15,7 @@ namespace SimpleWeb {
     int lflf = 0;
 
   public:
+    /// Match condition for asio::read_until to match both standard and non-standard HTTP header endings.
     std::pair<asio::buffers_iterator<asio::const_buffers_1>, bool> operator()(asio::buffers_iterator<asio::const_buffers_1> begin, asio::buffers_iterator<asio::const_buffers_1> end) {
       auto it = begin;
       for(; it != end; ++it) {
@@ -72,7 +73,7 @@ namespace SimpleWeb {
       std::size_t size() noexcept {
         return streambuf.size();
       }
-      /// Convenience function to return std::string. The stream buffer is consumed.
+      /// Convenience function to return content as a string. The stream buffer is consumed.
       std::string string() noexcept {
         try {
           std::string str;
@@ -188,15 +189,14 @@ namespace SimpleWeb {
     };
 
   public:
-    /// Set before calling request
+    /// Set before calling a request function.
     Config config;
 
-    /// If you have your own asio::io_service, store its pointer here before calling request().
-    /// When using asynchronous requests, running the io_service is up to the programmer.
+    /// If you want to reuse an already created asio::io_service, store its pointer here before calling a request function.
     std::shared_ptr<io_context> io_service;
 
     /// Convenience function to perform synchronous request. The io_service is run within this function.
-    /// If reusing the io_service for other tasks, use the asynchronous request functions instead.
+    /// If you reuse the io_service for other tasks, use the asynchronous request functions instead.
     /// Do not use concurrently with the asynchronous request functions.
     /// When requesting Server-Sent Events: will throw on error::eof, please use asynchronous request functions instead.
     std::shared_ptr<Response> request(const std::string &method, const std::string &path = {"/"}, string_view content = {}, const CaseInsensitiveMultimap &header = CaseInsensitiveMultimap()) {
@@ -226,7 +226,7 @@ namespace SimpleWeb {
     }
 
     /// Convenience function to perform synchronous request. The io_service is run within this function.
-    /// If reusing the io_service for other tasks, use the asynchronous request functions instead.
+    /// If you reuse the io_service for other tasks, use the asynchronous request functions instead.
     /// Do not use concurrently with the asynchronous request functions.
     /// When requesting Server-Sent Events: will throw on error::eof, please use asynchronous request functions instead.
     std::shared_ptr<Response> request(const std::string &method, const std::string &path, std::istream &content, const CaseInsensitiveMultimap &header = CaseInsensitiveMultimap()) {
@@ -255,7 +255,7 @@ namespace SimpleWeb {
       return response;
     }
 
-    /// Asynchronous request where setting and/or running Client's io_service is required.
+    /// Asynchronous request where running Client's io_service is required.
     /// Do not use concurrently with the synchronous request functions.
     /// When requesting Server-Sent Events: request_callback might be called more than twice, first call with empty contents on open, and with ec = error::eof on last call
     void request(const std::string &method, const std::string &path, string_view content, const CaseInsensitiveMultimap &header,
@@ -307,30 +307,30 @@ namespace SimpleWeb {
       connect(session);
     }
 
-    /// Asynchronous request where setting and/or running Client's io_service is required.
+    /// Asynchronous request where running Client's io_service is required.
     /// Do not use concurrently with the synchronous request functions.
     /// When requesting Server-Sent Events: request_callback might be called more than twice, first call with empty contents on open, and with ec = error::eof on last call
     void request(const std::string &method, const std::string &path, string_view content,
                  std::function<void(std::shared_ptr<Response>, const error_code &)> &&request_callback_) {
       request(method, path, content, CaseInsensitiveMultimap(), std::move(request_callback_));
     }
 
-    /// Asynchronous request where setting and/or running Client's io_service is required.
+    /// Asynchronous request where running Client's io_service is required.
     /// Do not use concurrently with the synchronous request functions.
     /// When requesting Server-Sent Events: request_callback might be called more than twice, first call with empty contents on open, and with ec = error::eof on last call
     void request(const std::string &method, const std::string &path,
                  std::function<void(std::shared_ptr<Response>, const error_code &)> &&request_callback_) {
       request(method, path, std::string(), CaseInsensitiveMultimap(), std::move(request_callback_));
     }
 
-    /// Asynchronous request where setting and/or running Client's io_service is required.
+    /// Asynchronous request where running Client's io_service is required.
     /// Do not use concurrently with the synchronous request functions.
     /// When requesting Server-Sent Events: request_callback might be called more than twice, first call with empty contents on open, and with ec = error::eof on last call
     void request(const std::string &method, std::function<void(std::shared_ptr<Response>, const error_code &)> &&request_callback_) {
       request(method, std::string("/"), std::string(), CaseInsensitiveMultimap(), std::move(request_callback_));
     }
 
-    /// Asynchronous request where setting and/or running Client's io_service is required.
+    /// Asynchronous request where running Client's io_service is required.
     /// Do not use concurrently with the synchronous request functions.
     /// When requesting Server-Sent Events: request_callback might be called more than twice, first call with empty contents on open, and with ec = error::eof on last call
     void request(const std::string &method, const std::string &path, std::istream &content, const CaseInsensitiveMultimap &header,
@@ -386,15 +386,15 @@ namespace SimpleWeb {
       connect(session);
     }
 
-    /// Asynchronous request where setting and/or running Client's io_service is required.
+    /// Asynchronous request where running Client's io_service is required.
     /// Do not use concurrently with the synchronous request functions.
     /// When requesting Server-Sent Events: request_callback might be called more than twice, first call with empty contents on open, and with ec = error::eof on last call
     void request(const std::string &method, const std::string &path, std::istream &content,
                  std::function<void(std::shared_ptr<Response>, const error_code &)> &&request_callback_) {
       request(method, path, content, CaseInsensitiveMultimap(), std::move(request_callback_));
     }
 
-    /// Close connections
+    /// Close connections.
     void stop() noexcept {
       LockGuard lock(connections_mutex);
       for(auto it = connections.begin(); it != connections.end();) {
@@ -755,6 +755,11 @@ namespace SimpleWeb {
   template <>
   class Client<HTTP> : public ClientBase<HTTP> {
   public:
+    /**
+     * Constructs a client object.
+     *
+     * @param server_port_path Server resource given by host[:port][/path]
+     */
     Client(const std::string &server_port_path) noexcept : ClientBase<HTTP>::ClientBase(server_port_path, 80) {}
 
   protected:

client_https.hpp

@@ -15,11 +15,20 @@ namespace SimpleWeb {
   template <>
   class Client<HTTPS> : public ClientBase<HTTPS> {
   public:
-    Client(const std::string &server_port_path, bool verify_certificate = true, const std::string &cert_file = std::string(),
+    /**
+     * Constructs a client object.
+     *
+     * @param server_port_path   Server resource given by host[:port][/path]
+     * @param verify_certificate Set to true (default) to verify the server's certificate and hostname according to RFC 2818.
+     * @param certification_file If non-empty, sends the given certification file to server. Requires private_key_file.
+     * @param private_key_file   If non-empty, specifies the file containing the private key for certification_file. Requires certification_file.
+     * @param verify_file        If non-empty, use this certificate authority file to perform verification.
+     */
+    Client(const std::string &server_port_path, bool verify_certificate = true, const std::string &certification_file = std::string(),
            const std::string &private_key_file = std::string(), const std::string &verify_file = std::string())
         : ClientBase<HTTPS>::ClientBase(server_port_path, 443), context(asio::ssl::context::tlsv12) {
-      if(cert_file.size() > 0 && private_key_file.size() > 0) {
-        context.use_certificate_chain_file(cert_file);
+      if(certification_file.size() > 0 && private_key_file.size() > 0) {
+        context.use_certificate_chain_file(certification_file);
         context.use_private_key_file(private_key_file, asio::ssl::context::pem);
       }
 

crypto.hpp

@@ -27,7 +27,8 @@ namespace SimpleWeb {
   public:
     class Base64 {
     public:
-      static std::string encode(const std::string &ascii) noexcept {
+      /// Returns Base64 encoded string from input string.
+      static std::string encode(const std::string &input) noexcept {
         std::string base64;
 
         BIO *bio, *b64;
@@ -40,13 +41,13 @@ namespace SimpleWeb {
         BIO_set_mem_buf(b64, bptr, BIO_CLOSE);
 
         // Write directly to base64-buffer to avoid copy
-        auto base64_length = static_cast<std::size_t>(round(4 * ceil(static_cast<double>(ascii.size()) / 3.0)));
+        auto base64_length = static_cast<std::size_t>(round(4 * ceil(static_cast<double>(input.size()) / 3.0)));
         base64.resize(base64_length);
         bptr->length = 0;
         bptr->max = base64_length + 1;
         bptr->data = &base64[0];
 
-        if(BIO_write(b64, &ascii[0], static_cast<int>(ascii.size())) <= 0 || BIO_flush(b64) <= 0)
+        if(BIO_write(b64, &input[0], static_cast<int>(input.size())) <= 0 || BIO_flush(b64) <= 0)
           base64.clear();
 
         // To keep &base64[0] through BIO_free_all(b64)
@@ -59,6 +60,7 @@ namespace SimpleWeb {
         return base64;
       }
 
+      /// Returns Base64 decoded string from base64 input.
       static std::string decode(const std::string &base64) noexcept {
         std::string ascii;
 
@@ -88,7 +90,7 @@ namespace SimpleWeb {
       }
     };
 
-    /// Return hex string from bytes in input string.
+    /// Returns hex string from bytes in input string.
     static std::string to_hex_string(const std::string &input) noexcept {
       std::stringstream hex_stream;
       hex_stream << std::hex << std::internal << std::setfill('0');
@@ -97,6 +99,7 @@ namespace SimpleWeb {
       return hex_stream.str();
     }
 
+    /// Returns md5 hash value from input string.
     static std::string md5(const std::string &input, std::size_t iterations = 1) noexcept {
       std::string hash;
 
@@ -109,6 +112,7 @@ namespace SimpleWeb {
       return hash;
     }
 
+    /// Returns md5 hash value from input stream.
     static std::string md5(std::istream &stream, std::size_t iterations = 1) noexcept {
       MD5_CTX context;
       MD5_Init(&context);
@@ -126,6 +130,7 @@ namespace SimpleWeb {
       return hash;
     }
 
+    /// Returns sha1 hash value from input string.
     static std::string sha1(const std::string &input, std::size_t iterations = 1) noexcept {
       std::string hash;
 
@@ -138,6 +143,7 @@ namespace SimpleWeb {
       return hash;
     }
 
+    /// Returns sha1 hash value from input stream.
     static std::string sha1(std::istream &stream, std::size_t iterations = 1) noexcept {
       SHA_CTX context;
       SHA1_Init(&context);
@@ -155,6 +161,7 @@ namespace SimpleWeb {
       return hash;
     }
 
+    /// Returns sha256 hash value from input string.
     static std::string sha256(const std::string &input, std::size_t iterations = 1) noexcept {
       std::string hash;
 
@@ -167,6 +174,7 @@ namespace SimpleWeb {
       return hash;
     }
 
+    /// Returns sha256 hash value from input stream.
     static std::string sha256(std::istream &stream, std::size_t iterations = 1) noexcept {
       SHA256_CTX context;
       SHA256_Init(&context);
@@ -184,6 +192,7 @@ namespace SimpleWeb {
       return hash;
     }
 
+    /// Returns sha512 hash value from input string.
     static std::string sha512(const std::string &input, std::size_t iterations = 1) noexcept {
       std::string hash;
 
@@ -196,6 +205,7 @@ namespace SimpleWeb {
       return hash;
     }
 
+    /// Returns sha512 hash value from input stream.
     static std::string sha512(std::istream &stream, std::size_t iterations = 1) noexcept {
       SHA512_CTX context;
       SHA512_Init(&context);
@@ -213,7 +223,19 @@ namespace SimpleWeb {
       return hash;
     }
 
-    /// key_size is number of bytes of the returned key.
+    /// Returns PBKDF2 hash value from the given password
+    /// Input parameter key_size  number of bytes of the returned key.
+
+    /**
+     * Returns PBKDF2 derived key from the given password.
+     *
+     * @param password   The password to derive key from.
+     * @param salt       The salt to be used in the algorithm.
+     * @param iterations Number of iterations to be used in the algorithm.
+     * @param key_size   Number of bytes of the returned key.
+     *
+     * @return The PBKDF2 derived key.
+     */
     static std::string pbkdf2(const std::string &password, const std::string &salt, int iterations, int key_size) noexcept {
       std::string key;
       key.resize(static_cast<std::size_t>(key_size));

mutex.hpp

@@ -69,7 +69,7 @@
   THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis)
 
 namespace SimpleWeb {
-  /// Defines an annotated interface for mutexes.
+  /// Mutex class that is annotated for Clang Thread Safety Analysis.
   class CAPABILITY("mutex") Mutex {
     std::mutex mutex;
 
@@ -83,6 +83,7 @@ namespace SimpleWeb {
     }
   };
 
+  /// Scoped mutex guard class that is annotated for Clang Thread Safety Analysis.
   class SCOPED_CAPABILITY LockGuard {
     Mutex &mutex;
     bool locked = true;