From 44493edef3ae18ada50a2459eb2c073bc5da4a2f Mon Sep 17 00:00:00 2001
From: lganzzzo <lganzzzo@gmail.com>
Date: Mon, 9 Dec 2019 06:01:51 +0200
Subject: [PATCH] Better API docs.

---
 .../web/server/AsyncHttpConnectionHandler.hpp | 35 ++++++++-
 src/oatpp/web/server/HttpProcessor.hpp        | 74 ++++++++++++++++++-
 2 files changed, 103 insertions(+), 6 deletions(-)

diff --git a/src/oatpp/web/server/AsyncHttpConnectionHandler.hpp b/src/oatpp/web/server/AsyncHttpConnectionHandler.hpp
index 4a96dcbc..b3065eaa 100644
--- a/src/oatpp/web/server/AsyncHttpConnectionHandler.hpp
+++ b/src/oatpp/web/server/AsyncHttpConnectionHandler.hpp
@@ -39,31 +39,62 @@ namespace oatpp { namespace web { namespace server {
  * Asynchronous &id:oatpp::network::server::ConnectionHandler; for handling http communication.
  */
 class AsyncHttpConnectionHandler : public base::Countable, public network::server::ConnectionHandler {
-private:
-  typedef oatpp::web::protocol::http::incoming::BodyDecoder BodyDecoder;
 private:
   std::shared_ptr<oatpp::async::Executor> m_executor;
 private:
   std::shared_ptr<HttpProcessor::Components> m_components;
 public:
 
+  /**
+   * Constructor.
+   * @param components - &id:oatpp::web::server::HttpProcessor::Components;.
+   * @param threadCount - number of threads.
+   */
   AsyncHttpConnectionHandler(const std::shared_ptr<HttpProcessor::Components>& components, v_int32 threadCount = oatpp::async::Executor::VALUE_SUGGESTED);
+
+  /**
+   * Constructor.
+   * @param components - &id:oatpp::web::server::HttpProcessor::Components;.
+   * @param executor - &id:oatpp::async::Executor;.
+   */
   AsyncHttpConnectionHandler(const std::shared_ptr<HttpProcessor::Components>& components, const std::shared_ptr<oatpp::async::Executor>& executor);
 
+  /**
+   * Constructor.
+   * @param router - &id:oatpp::web::server::HttpRouter; to route incoming requests.
+   * @param threadCount - number of threads.
+   */
   AsyncHttpConnectionHandler(const std::shared_ptr<HttpRouter>& router, v_int32 threadCount = oatpp::async::Executor::VALUE_SUGGESTED)
     : AsyncHttpConnectionHandler(std::make_shared<HttpProcessor::Components>(router), threadCount)
   {}
 
+  /**
+   * Constructor.
+   * @param router - &id:oatpp::web::server::HttpRouter; to route incoming requests.
+   * @param executor - &id:oatpp::async::Executor;.
+   */
   AsyncHttpConnectionHandler(const std::shared_ptr<HttpRouter>& router, const std::shared_ptr<oatpp::async::Executor>& executor)
     : AsyncHttpConnectionHandler(std::make_shared<HttpProcessor::Components>(router), executor)
   {}
 
+  /**
+   * Constructor.
+   * @param router - &id:oatpp::web::server::HttpRouter; to route incoming requests.
+   * @param config - &id:oatpp::web::server::HttpProcessor::Config;.
+   * @param threadCount - number of threads.
+   */
   AsyncHttpConnectionHandler(const std::shared_ptr<HttpRouter>& router,
                              const std::shared_ptr<HttpProcessor::Config>& config,
                              v_int32 threadCount = oatpp::async::Executor::VALUE_SUGGESTED)
     : AsyncHttpConnectionHandler(std::make_shared<HttpProcessor::Components>(router, config), threadCount)
   {}
 
+  /**
+   * Constructor.
+   * @param router - &id:oatpp::web::server::HttpRouter; to route incoming requests.
+   * @param config - &id:oatpp::web::server::HttpProcessor::Config;.
+   * @param executor - &id:oatpp::async::Executor;.
+   */
   AsyncHttpConnectionHandler(const std::shared_ptr<HttpRouter>& router,
                              const std::shared_ptr<HttpProcessor::Config>& config,
                              const std::shared_ptr<oatpp::async::Executor>& executor)
diff --git a/src/oatpp/web/server/HttpProcessor.hpp b/src/oatpp/web/server/HttpProcessor.hpp
index e1e27ee3..4a26d28c 100644
--- a/src/oatpp/web/server/HttpProcessor.hpp
+++ b/src/oatpp/web/server/HttpProcessor.hpp
@@ -40,12 +40,14 @@
 #include "oatpp/core/async/Processor.hpp"
 
 namespace oatpp { namespace web { namespace server {
-  
+
+/**
+ * HttpProcessor. Helper class to handle HTTP processing.
+ */
 class HttpProcessor {
 public:
   typedef oatpp::collection::LinkedList<std::shared_ptr<oatpp::web::server::handler::RequestInterceptor>> RequestInterceptors;
   typedef oatpp::web::protocol::http::incoming::RequestHeadersReader RequestHeadersReader;
-
 public:
 
   /**
@@ -87,22 +89,61 @@ public:
 
 public:
 
+  /**
+   * Collection of components needed to serve http-connection.
+   */
   struct Components {
 
+    /**
+     * Constructor.
+     * @param pRouter
+     * @param pBodyDecoder
+     * @param pErrorHandler
+     * @param pRequestInterceptors
+     * @param pConfig
+     */
     Components(const std::shared_ptr<HttpRouter>& pRouter,
                const std::shared_ptr<const oatpp::web::protocol::http::incoming::BodyDecoder>& pBodyDecoder,
                const std::shared_ptr<handler::ErrorHandler>& pErrorHandler,
                const std::shared_ptr<RequestInterceptors>& pRequestInterceptors,
                const std::shared_ptr<Config>& pConfig);
 
+    /**
+     * Constructor.
+     * @param pRouter
+     */
     Components(const std::shared_ptr<HttpRouter>& pRouter);
 
+    /**
+     * Constructor.
+     * @param pRouter
+     * @param pConfig
+     */
     Components(const std::shared_ptr<HttpRouter>& pRouter, const std::shared_ptr<Config>& pConfig);
 
+    /**
+     * Router to route incoming requests. &id:oatpp::web::server::HttpRouter;.
+     */
     std::shared_ptr<HttpRouter> router;
+
+    /**
+     * Body decoder. &id:oatpp::web::protocol::http::incoming::BodyDecoder;.
+     */
     std::shared_ptr<const oatpp::web::protocol::http::incoming::BodyDecoder> bodyDecoder;
+
+    /**
+     * Error handler. &id:oatpp::web::server::handler::ErrorHandler;.
+     */
     std::shared_ptr<handler::ErrorHandler> errorHandler;
+
+    /**
+     * Collection of request interceptors. &id:oatpp::web::server::handler::RequestInterceptor;.
+     */
     std::shared_ptr<RequestInterceptors> requestInterceptors;
+
+    /**
+     * Resource allocation config. &l:HttpProcessor::Config;.
+     */
     std::shared_ptr<Config> config;
 
   };
@@ -117,19 +158,38 @@ private:
 
 public:
 
+  /**
+   * Connection serving task. <br>
+   * Usege example: <br>
+   * `std::thread thread(&HttpProcessor::Task::run, HttpProcessor::Task(components, connection));`
+   */
   class Task : public base::Countable {
   private:
     std::shared_ptr<Components> m_components;
     std::shared_ptr<oatpp::data::stream::IOStream> m_connection;
   public:
+
+    /**
+     * Constructor.
+     * @param components - &l:HttpProcessor::Components;.
+     * @param connection - &id:oatpp::data::stream::IOStream;.
+     */
     Task(const std::shared_ptr<Components>& components,
          const std::shared_ptr<oatpp::data::stream::IOStream>& connection);
   public:
+
+    /**
+     * Run loop.
+     */
     void run();
+
   };
   
 public:
-  
+
+  /**
+   * Connection serving coroutiner - &id:oatpp::async::Coroutine;.
+   */
   class Coroutine : public oatpp::async::Coroutine<HttpProcessor::Coroutine> {
   private:
     std::shared_ptr<Components> m_components;
@@ -144,7 +204,13 @@ public:
     std::shared_ptr<protocol::http::incoming::Request> m_currentRequest;
     std::shared_ptr<protocol::http::outgoing::Response> m_currentResponse;
   public:
-    
+
+
+    /**
+     * Constructor.
+     * @param components - &l:HttpProcessor::Components;.
+     * @param connection - &id:oatpp::data::stream::IOStream;.
+     */
     Coroutine(const std::shared_ptr<Components>& components,
               const std::shared_ptr<oatpp::data::stream::IOStream>& connection);