From 3228244cebac0d82ccc13372c53d3918bfdaa363 Mon Sep 17 00:00:00 2001 From: Nabzokek Date: Sat, 20 Apr 2024 21:40:11 -0400 Subject: [PATCH 1/6] Added documentation of "crow::App", "crow::SimpleApp", "crow" (namespace), all macros defined in "crow/app.h". --- Doxyfile | 4 +- include/crow/app.h | 267 ++++++++++++++++++++++++++++-------- include/crow/http_request.h | 2 +- include/crow/http_server.h | 3 +- include/crow/middleware.h | 4 + 5 files changed, 219 insertions(+), 61 deletions(-) diff --git a/Doxyfile b/Doxyfile index ca15eb685..b4e37870b 100644 --- a/Doxyfile +++ b/Doxyfile @@ -499,7 +499,7 @@ NUM_PROC_THREADS = 1 # normally produced when WARNINGS is set to YES. # The default value is: NO. -EXTRACT_ALL = NO +EXTRACT_ALL = YES # DEBUG # If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will # be included in the documentation. @@ -772,7 +772,7 @@ SHOW_FILES = YES # Folder Tree View (if specified). # The default value is: YES. -SHOW_NAMESPACES = NO +SHOW_NAMESPACES = YES # The FILE_VERSION_FILTER tag can be used to specify a program or script that # doxygen should invoke to get the current version for each file (typically from diff --git a/include/crow/app.h b/include/crow/app.h index a91e992a6..619d0df02 100644 --- a/include/crow/app.h +++ b/include/crow/app.h @@ -24,50 +24,181 @@ #include "crow/compression.h" #endif + #ifdef CROW_MSVC_WORKAROUND -#define CROW_ROUTE(app, url) app.route_dynamic(url) -#define CROW_BP_ROUTE(blueprint, url) blueprint.new_rule_dynamic(url) -#else + +#define CROW_ROUTE(app, url) app.route_dynamic(url) // See the documentation in the comment bellow. +#define CROW_BP_ROUTE(blueprint, url) blueprint.new_rule_dynamic(url) // See the documentation in the comment bellow. + +#else // #ifdef CROW_MSVC_WORKAROUND + +/** + * \def CROW_ROUTE(app, url) + * \brief Creates a route for app using a rule. + * + * It use crow::Crow::route_dynamic or crow::Crow::route to define + * a rule for your application. It's usage is like this: + * + * ```cpp + * auto app = crow::SimpleApp(); // or crow::App() + * CROW_ROUTE(app, "/") + * ([](){ + * return "

Hello, world!

"; + * }); + * ``` + * + * This is the recommended way to define routes in a crow application. + * \see [Page of guide "Routes"](https://crowcpp.org/master/guides/routes/). + */ #define CROW_ROUTE(app, url) app.template route(url) + +/** + * \def CROW_BP_ROUTE(blueprint, url) + * \brief Creates a route for a blueprint using a rule. + * + * It may use crow::Blueprint::new_rule_dynamic or + * crow::Blueprint::new_rule_tagged to define a new rule for an + * given blueprint. It's usage is similar to CROW_ROUTE macro: + * + * ```cpp + * crow::Blueprint my_bp(); + * CROW_BP_ROUTE(my_bp, "/") + * ([](){ + * return "

Hello, world!

"; + * }); + * ``` + * + * This is the recommended way to define routes in a crow blueprint + * because of its compile-time capabilities. + * + * \see [Page of the guide "Blueprints"](https://crowcpp.org/master/guides/blueprints/). + */ #define CROW_BP_ROUTE(blueprint, url) blueprint.new_rule_tagged(url) + +/** + * \def CROW_WEBSOCKET_ROUTE(app, url) + * \brief Defines WebSocket route for app. + * + * It binds a WebSocket route to app. + * for more information about how implement WebSockets in your + * application. The usage syntax of this macro is like this: + * + * ```cpp + * auto app = crow::SimpleApp(); // or crow::App() + * CROW_WEBSOCKET_ROUTE(app, "/ws") + * .onopen([&](crow::websocket::connection& conn){ + * do_something(); + * }) + * .onclose([&](crow::websocket::connection& conn, const std::string& reason){ + * do_something(); + * }) + * .onmessage([&](crow::websocket::connection&, const std::string& data, bool is_binary){ + * if (is_binary) + * do_something(data); + * else + * do_something_else(data); + * }); + * ``` + * + * \see [Page of the guide "WebSockets"](https://crowcpp.org/master/guides/websockets/). + */ #define CROW_WEBSOCKET_ROUTE(app, url) app.route(url).websocket::type>(&app) + +/** + * \def CROW_MIDDLEWARES(app, ...) + * \brief Enable a Middleware for an specific route in app + * or blueprint. + * + * It defines the usage of a Middleware in one route. And it + * can be used in both crow::SimpleApp (and crow::App) + * instances and crow::Blueprint. Its usage syntax is like this: + * + * ```cpp + * auto app = crow::SimpleApp(); // or crow::App() + * CROW_ROUTE(app, "/with_middleware") + * .CROW_MIDDLEWARES(app, LocalMiddleware) // Can be used more than one + * ([]() { // middleware. + * return "Hello world!"; + * }); + * ``` + * + * \see [Page of the guide "Middlewares"](https://crowcpp.org/master/guides/middleware/). + */ #define CROW_MIDDLEWARES(app, ...) template middlewares::type, __VA_ARGS__>() -#endif + +#endif // #ifdef CROW_MSVC_WORKAROUND + +/** + * \def CROW_CATCHALL_ROUTE(app) + * \brief Defines a custom catchall route for app using a + * custom rule. + * + * It defines a handler when the client make a request for an + * undefined route. Instead of just reply with a `404` status + * code (default behavior), you can define a custom handler + * using this macro. + * + * \see [Page of the guide "Routes" (Catchall routes)](https://crowcpp.org/master/guides/routes/#catchall-routes). + */ #define CROW_CATCHALL_ROUTE(app) app.catchall_route() + +/** + * \def CROW_BP_CATCHALL_ROUTE(blueprint) + * \brief Defines a custom catchall route for blueprint + * using a custom rule. + * + * It defines a handler when the client make a request for an + * undefined route in the blueprint. + * + * \see [Page of the guide "Blueprint" (Define a custom Catchall route)](https://crowcpp.org/master/guides/blueprints/#define-a-custom-catchall-route). + */ #define CROW_BP_CATCHALL_ROUTE(blueprint) blueprint.catchall_rule() + +/** + * \namespace crow + * \brief The main namespace. In this namespace are the most important + * classes and functions of the library. + * + * Within this namespace, the Crow class is defined, whose instances + * represent web applications with routes and rules. + */ namespace crow { #ifdef CROW_ENABLE_SSL using ssl_context_t = asio::ssl::context; #endif - /// The main server application - - /// - /// Use `SimpleApp` or `App` + /** + * \class Crow + * \brief The main server application class. + * + * Use SimpleApp or App instead of + * directly instantiate this class. + */ template class Crow { public: - /// This crow application + /// \brief This is the crow application using self_t = Crow; - /// The HTTP server + + /// \brief The HTTP server using server_t = Server; + #ifdef CROW_ENABLE_SSL - /// An HTTP server that runs on SSL with an SSLAdaptor + /// \brief An HTTP server that runs on SSL with an SSLAdaptor using ssl_server_t = Server; #endif Crow() {} - /// Construct Crow with a subset of middleware + /// \brief Construct Crow with a subset of middleware template Crow(Ts&&... ts): middlewares_(make_middleware_tuple(std::forward(ts)...)) {} - /// Process an Upgrade request - + /// \brief Process an Upgrade request /// /// Currently used to upgrade an HTTP connection to a WebSocket connection template @@ -76,19 +207,19 @@ namespace crow router_.handle_upgrade(req, res, adaptor); } - /// Process only the method and URL of a request and provide a route (or an error response) + /// \brief Process only the method and URL of a request and provide a route (or an error response) std::unique_ptr handle_initial(request& req, response& res) { return router_.handle_initial(req, res); } - /// Process the fully parsed request and generate a response for it + /// \brief Process the fully parsed request and generate a response for it void handle(request& req, response& res, std::unique_ptr& found) { router_.handle(req, res, *found); } - /// Process a fully parsed request from start to finish (primarily used for debugging) + /// \brief Process a fully parsed request from start to finish (primarily used for debugging) void handle_full(request& req, response& res) { auto found = handle_initial(req, res); @@ -96,13 +227,13 @@ namespace crow handle(req, res, found); } - /// Create a dynamic route using a rule (**Use CROW_ROUTE instead**) + /// \brief Create a dynamic route using a rule (**Use CROW_ROUTE instead**) DynamicRule& route_dynamic(const std::string& rule) { return router_.new_rule_dynamic(rule); } - /// Create a route using a rule (**Use CROW_ROUTE instead**) + /// \brief Create a route using a rule (**Use CROW_ROUTE instead**) template #ifdef CROW_GCC83_WORKAROUND auto& route(const std::string& rule) @@ -118,89 +249,92 @@ namespace crow return router_.new_rule_tagged(rule); } - /// Create a route for any requests without a proper route (**Use CROW_CATCHALL_ROUTE instead**) + /// \brief Create a route for any requests without a proper route (**Use CROW_CATCHALL_ROUTE instead**) CatchallRule& catchall_route() { return router_.catchall_rule(); } - /// Set the default max payload size for websockets + /// \brief Set the default max payload size for websockets self_t& websocket_max_payload(uint64_t max_payload) { max_payload_ = max_payload; return *this; } - /// Get the default max payload size for websockets + /// \brief Get the default max payload size for websockets uint64_t websocket_max_payload() { return max_payload_; } + /// \brief (TODO) self_t& signal_clear() { signals_.clear(); return *this; } + /// \brief (TODO) self_t& signal_add(int signal_number) { signals_.push_back(signal_number); return *this; } + /// \brief (TODO) std::vector signals() { return signals_; } - /// Set the port that Crow will handle requests on + /// \brief Set the port that Crow will handle requests on self_t& port(std::uint16_t port) { port_ = port; return *this; } - /// Get the port that Crow will handle requests on + /// \brief Get the port that Crow will handle requests on std::uint16_t port() { return port_; } - /// Set the connection timeout in seconds (default is 5) + /// \brief Set the connection timeout in seconds (default is 5) self_t& timeout(std::uint8_t timeout) { timeout_ = timeout; return *this; } - /// Set the server name + /// \brief Set the server name self_t& server_name(std::string server_name) { server_name_ = server_name; return *this; } - /// The IP address that Crow will handle requests on (default is 0.0.0.0) + /// \brief The IP address that Crow will handle requests on (default is 0.0.0.0) self_t& bindaddr(std::string bindaddr) { bindaddr_ = bindaddr; return *this; } - /// Get the address that Crow will handle requests on + /// \brief Get the address that Crow will handle requests on std::string bindaddr() { return bindaddr_; } - /// Run the server on multiple threads using all available threads + /// \brief Run the server on multiple threads using all available threads self_t& multithreaded() { return concurrency(std::thread::hardware_concurrency()); } - /// Run the server on multiple threads using a specific number + /// \brief Run the server on multiple threads using a specific number self_t& concurrency(std::uint16_t concurrency) { if (concurrency < 2) // Crow can have a minimum of 2 threads running @@ -209,29 +343,27 @@ namespace crow return *this; } - /// Get the number of threads that server is using + /// \brief Get the number of threads that server is using std::uint16_t concurrency() { return concurrency_; } - /// Set the server's log level - + /// \brief Set the server's log level /// - /// Possible values are:
- /// crow::LogLevel::Debug (0)
- /// crow::LogLevel::Info (1)
- /// crow::LogLevel::Warning (2)
- /// crow::LogLevel::Error (3)
- /// crow::LogLevel::Critical (4)
+ /// Possible values are: + /// - crow::LogLevel::Debug (0) + /// - crow::LogLevel::Info (1) + /// - crow::LogLevel::Warning (2) + /// - crow::LogLevel::Error (3) + /// - crow::LogLevel::Critical (4) self_t& loglevel(LogLevel level) { crow::logger::setLogLevel(level); return *this; } - /// Set the response body size (in bytes) beyond which Crow automatically streams responses (Default is 1MiB) - + /// \brief Set the response body size (in bytes) beyond which Crow automatically streams responses (Default is 1MiB) /// /// Any streamed response is unaffected by Crow's timer, and therefore won't timeout before a response is fully sent. self_t& stream_threshold(size_t threshold) @@ -240,7 +372,7 @@ namespace crow return *this; } - /// Get the response body size (in bytes) beyond which Crow automatically streams responses + /// \brief Get the response body size (in bytes) beyond which Crow automatically streams responses size_t& stream_threshold() { return res_stream_threshold_; @@ -252,8 +384,7 @@ namespace crow return *this; } - /// Set the function to call to handle uncaught exceptions generated in routes (Default generates error 500). - + /// \brief Set the function to call to handle uncaught exceptions generated in routes (Default generates error 500). /// /// The function must have the following signature: void(crow::response&). /// It must set the response passed in argument to the function, which will be sent back to the client. @@ -265,12 +396,13 @@ namespace crow return *this; } + /// \brief (TODO) std::function& exception_handler() { return router_.exception_handler(); } - /// Set a custom duration and function to run on every tick + /// \brief Set a custom duration and function to run on every tick template self_t& tick(Duration d, Func f) { @@ -280,6 +412,7 @@ namespace crow } #ifdef CROW_ENABLE_COMPRESSION + /// \brief (TODO) self_t& use_compression(compression::algorithm algorithm) { comp_algorithm_ = algorithm; @@ -287,18 +420,20 @@ namespace crow return *this; } + /// \brief (TODO) compression::algorithm compression_algorithm() { return comp_algorithm_; } + /// \brief (TODO) bool compression_used() const { return compression_used_; } #endif - /// Apply blueprints + /// \brief Apply blueprints void add_blueprint() { #if defined(__APPLE__) || defined(__MACH__) @@ -321,7 +456,7 @@ namespace crow router_.validate_bp(); } - /// Go through the rules, upgrade them if possible, and add them to the list of rules + /// \brief Go through the rules, upgrade them if possible, and add them to the list of rules void add_static_dir() { if (are_static_routes_added()) return; @@ -335,13 +470,13 @@ namespace crow set_static_routes_added(); } - /// A wrapper for `validate()` in the router + /// \brief A wrapper for `validate()` in the router void validate() { router_.validate(); } - /// Run the server + /// \brief Run the server void run() { #ifndef CROW_DISABLE_STATIC_DIR @@ -377,7 +512,7 @@ namespace crow } } - /// Non-blocking version of \ref run() + /// \brief Non-blocking version of \ref run() /// /// The output from this method needs to be saved into a variable! /// Otherwise the call will be made on the same thread. @@ -388,7 +523,7 @@ namespace crow }); } - /// Stop the server + /// \brief Stop the server void stop() { #ifdef CROW_ENABLE_SSL @@ -410,17 +545,19 @@ namespace crow } } + /// \brief (TODO) void add_websocket(crow::websocket::connection* conn) { websockets_.push_back(conn); } + /// \brief (TODO) void remove_websocket(crow::websocket::connection* conn) { websockets_.erase(std::remove(websockets_.begin(), websockets_.end(), conn), websockets_.end()); } - /// Print the routing paths defined for each HTTP method + /// \brief Print the routing paths defined for each HTTP method void debug_print() { CROW_LOG_DEBUG << "Routing:"; @@ -430,7 +567,7 @@ namespace crow #ifdef CROW_ENABLE_SSL - /// Use certificate and key files for SSL + /// \brief Use certificate and key files for SSL self_t& ssl_file(const std::string& crt_filename, const std::string& key_filename) { ssl_used_ = true; @@ -443,7 +580,7 @@ namespace crow return *this; } - /// Use .pem file for SSL + /// \brief Use `.pem` file for SSL self_t& ssl_file(const std::string& pem_filename) { ssl_used_ = true; @@ -455,7 +592,7 @@ namespace crow return *this; } - /// Use certificate chain and key files for SSL + /// \brief Use certificate chain and key files for SSL self_t& ssl_chainfile(const std::string& crt_filename, const std::string& key_filename) { ssl_used_ = true; @@ -468,6 +605,7 @@ namespace crow return *this; } + /// \brief (TODO) self_t& ssl(asio::ssl::context&& ctx) { ssl_used_ = true; @@ -475,11 +613,13 @@ namespace crow return *this; } + /// \brief (TODO) bool ssl_used() const { return ssl_used_; } #else + /// \brief (TODO) template self_t& ssl_file(T&&, Remain&&...) { @@ -491,6 +631,7 @@ namespace crow return *this; } + /// \brief (TODO) template self_t& ssl_chainfile(T&&, Remain&&...) { @@ -502,6 +643,7 @@ namespace crow return *this; } + /// \brief (TODO) template self_t& ssl(T&&) { @@ -513,6 +655,7 @@ namespace crow return *this; } + /// \brief (TODO) bool ssl_used() const { return false; @@ -530,13 +673,14 @@ namespace crow return ctx.template get(); } + /// \brief (TODO) template T& get_middleware() { return utility::get_element_by_type(middlewares_); } - /// Wait until the server has properly started + /// \brief Wait until the server has properly started void wait_for_server_start() { { @@ -553,6 +697,7 @@ namespace crow } private: + /// \brief TODO (But it's not so necessary). template std::tuple make_middleware_tuple(Ts&&... ts) { @@ -562,7 +707,7 @@ namespace crow black_magic::tuple_extract(fwd))...); } - /// Notify anything using `wait_for_server_start()` to proceed + /// \brief Notify anything using \ref wait_for_server_start() to proceed void notify_server_start() { std::unique_lock lock(start_mutex_); @@ -570,10 +715,12 @@ namespace crow cv_started_.notify_all(); } + /// \brief TODO (But it's not so necessary). void set_static_routes_added() { static_routes_added_ = true; } + /// \brief TODO (But it's not so necessary). bool are_static_routes_added() { return static_routes_added_; } @@ -614,7 +761,13 @@ namespace crow std::mutex start_mutex_; std::vector websockets_; }; + + /// \brief Alias of Crow. Useful if you want + /// a instance of an Crow application that require Middlewares template using App = Crow; + + /// \brief Alias of Crow<>. Useful if you want a instance of + /// an Crow application that doesn't require of Middlewares using SimpleApp = Crow<>; } // namespace crow diff --git a/include/crow/http_request.h b/include/crow/http_request.h index daab8271d..3b71e1b60 100644 --- a/include/crow/http_request.h +++ b/include/crow/http_request.h @@ -13,7 +13,7 @@ #include "crow/ci_map.h" #include "crow/query_string.h" -namespace crow +namespace crow // NOTE: Already documented in "crow/app.h" { #ifdef CROW_USE_BOOST namespace asio = boost::asio; diff --git a/include/crow/http_server.h b/include/crow/http_server.h index 961776184..c2737d868 100644 --- a/include/crow/http_server.h +++ b/include/crow/http_server.h @@ -27,7 +27,8 @@ #include "crow/logging.h" #include "crow/task_timer.h" -namespace crow + +namespace crow // NOTE: Already documented in "crow/app.h" { #ifdef CROW_USE_BOOST namespace asio = boost::asio; diff --git a/include/crow/middleware.h b/include/crow/middleware.h index cdacf303e..3259816df 100644 --- a/include/crow/middleware.h +++ b/include/crow/middleware.h @@ -18,6 +18,10 @@ namespace crow using call_global = std::false_type; }; + /** + * \namespace detail + * \brief TODO + */ namespace detail { template From 8f414b35b3ba894bbf385d3d8dbccd0487ed877f Mon Sep 17 00:00:00 2001 From: Nabzokek Date: Mon, 22 Apr 2024 10:29:52 -0400 Subject: [PATCH 2/6] Added documentation entry for file crow/TinySHA1.hpp, namespace sha1, class sha1::SHA1, namespace crow and namespace crow::websocket --- include/crow/TinySHA1.hpp | 14 ++++++++++++-- include/crow/app.h | 30 ++++++++++++++++-------------- include/crow/compression.h | 6 +++++- include/crow/json.h | 6 +++++- include/crow/middleware.h | 4 ++-- include/crow/routing.h | 2 +- include/crow/websocket.h | 10 +++++++++- 7 files changed, 50 insertions(+), 22 deletions(-) diff --git a/include/crow/TinySHA1.hpp b/include/crow/TinySHA1.hpp index 70af046e6..fa679307d 100644 --- a/include/crow/TinySHA1.hpp +++ b/include/crow/TinySHA1.hpp @@ -1,6 +1,6 @@ /* - * - * TinySHA1 - a header only implementation of the SHA1 algorithm in C++. Based + * \file TinySHA1.hpp + * \brief TinySHA1 - a header only implementation of the SHA1 algorithm in C++. Based * on the implementation in boost::uuid::details. * * SHA1 Wikipedia Page: http://en.wikipedia.org/wiki/SHA-1 @@ -25,8 +25,18 @@ #include #include #include + +/** + * \namespace sha1 + * \brief Here is defined the SHA1 class + */ namespace sha1 { + /** + * \class SHA1 + * \brief A tiny SHA1 algorithm implementation used internally in the + * Crow server (specifically in crow/websocket.h). + */ class SHA1 { public: diff --git a/include/crow/app.h b/include/crow/app.h index 619d0df02..24a4a4181 100644 --- a/include/crow/app.h +++ b/include/crow/app.h @@ -22,7 +22,7 @@ #include "crow/websocket.h" #ifdef CROW_ENABLE_COMPRESSION #include "crow/compression.h" -#endif +#endif // #ifdef CROW_ENABLE_COMPRESSION #ifdef CROW_MSVC_WORKAROUND @@ -56,9 +56,9 @@ * \def CROW_BP_ROUTE(blueprint, url) * \brief Creates a route for a blueprint using a rule. * - * It may use crow::Blueprint::new_rule_dynamic or - * crow::Blueprint::new_rule_tagged to define a new rule for an - * given blueprint. It's usage is similar to CROW_ROUTE macro: + * It may use crow::Blueprint::new_rule_dynamic or crow::Blueprint::new_rule_tagged + * to define a new rule for an given blueprint. It's usage is similar + * to CROW_ROUTE macro: * * ```cpp * crow::Blueprint my_bp(); @@ -79,9 +79,9 @@ * \def CROW_WEBSOCKET_ROUTE(app, url) * \brief Defines WebSocket route for app. * - * It binds a WebSocket route to app. - * for more information about how implement WebSockets in your - * application. The usage syntax of this macro is like this: + * It binds a WebSocket route to app. Easy solution to implement + * WebSockets in your app. The usage syntax of this macro is + * like this: * * ```cpp * auto app = crow::SimpleApp(); // or crow::App() @@ -110,8 +110,8 @@ * or blueprint. * * It defines the usage of a Middleware in one route. And it - * can be used in both crow::SimpleApp (and crow::App) - * instances and crow::Blueprint. Its usage syntax is like this: + * can be used in both crow::SimpleApp (and crow::App) instances and + * crow::Blueprint. Its usage syntax is like this: * * ```cpp * auto app = crow::SimpleApp(); // or crow::App() @@ -157,11 +157,12 @@ /** * \namespace crow - * \brief The main namespace. In this namespace are the most important - * classes and functions of the library. + * \brief The main namespace of the library. In this namespace + * is defined the most important classes and functions of the + * library. * - * Within this namespace, the Crow class is defined, whose instances - * represent web applications with routes and rules. + * Within this namespace, the Crow class, Router class, Connection + * class, and other are defined. */ namespace crow { @@ -172,7 +173,7 @@ namespace crow * \class Crow * \brief The main server application class. * - * Use SimpleApp or App instead of + * Use crow::SimpleApp or crow::App instead of * directly instantiate this class. */ template @@ -378,6 +379,7 @@ namespace crow return res_stream_threshold_; } + /// \brief (TODO) self_t& register_blueprint(Blueprint& blueprint) { router_.register_blueprint(blueprint); diff --git a/include/crow/compression.h b/include/crow/compression.h index c33cb426e..518bc8163 100644 --- a/include/crow/compression.h +++ b/include/crow/compression.h @@ -5,8 +5,12 @@ #include // http://zlib.net/manual.html -namespace crow +namespace crow // NOTE: Already documented in "crow/app.h" { + /** + * \namespace crow::compression + * \brief TODO + */ namespace compression { // Values used in the 'windowBits' parameter for deflateInit2. diff --git a/include/crow/json.h b/include/crow/json.h index f4b607f03..cfd9464ca 100644 --- a/include/crow/json.h +++ b/include/crow/json.h @@ -25,13 +25,17 @@ using std::isinf; using std::isnan; -namespace crow +namespace crow // NOTE: Already documented in "crow/app.h" { namespace mustache { class template_t; } + /** + * \namespace crow::json + * \brief TODO + */ namespace json { inline void escape(const std::string& str, std::string& ret) diff --git a/include/crow/middleware.h b/include/crow/middleware.h index 3259816df..f241b1fb8 100644 --- a/include/crow/middleware.h +++ b/include/crow/middleware.h @@ -9,7 +9,7 @@ #include #include -namespace crow +namespace crow // NOTE: Already documented in "crow/app.h" { /// Local middleware should extend ILocalMiddleware @@ -19,7 +19,7 @@ namespace crow }; /** - * \namespace detail + * \namespace crow::detail * \brief TODO */ namespace detail diff --git a/include/crow/routing.h b/include/crow/routing.h index 3ec90b959..956fa49be 100644 --- a/include/crow/routing.h +++ b/include/crow/routing.h @@ -18,7 +18,7 @@ #include "crow/mustache.h" #include "crow/middleware.h" -namespace crow +namespace crow // NOTE: Already documented in "crow/app.h" { constexpr const uint16_t INVALID_BP_ID{((uint16_t)-1)}; diff --git a/include/crow/websocket.h b/include/crow/websocket.h index 13027165b..3dec4dc38 100644 --- a/include/crow/websocket.h +++ b/include/crow/websocket.h @@ -6,7 +6,7 @@ #include "crow/TinySHA1.hpp" #include "crow/utility.h" -namespace crow +namespace crow // NOTE: Already documented in "crow/app.h" { #ifdef CROW_USE_BOOST namespace asio = boost::asio; @@ -14,6 +14,14 @@ namespace crow #else using error_code = asio::error_code; #endif + + /** + * \namespace crow::websocket + * \brief Namespace that includes the \ref Connection class + * and \ref connection struct. Useful for WebSockets connection. + * + * Used specially in crow/websocket.h, crow/app.h and crow/routing.h + */ namespace websocket { enum class WebSocketReadState From e2175061fa3a5a00fb02df82fcab93e92950a077 Mon Sep 17 00:00:00 2001 From: Nabzokek Date: Mon, 22 Apr 2024 10:48:56 -0400 Subject: [PATCH 3/6] Documented crow/app.h and also improved crow/TinySHA1.hpp documentation --- include/crow/TinySHA1.hpp | 17 ++++++++++++----- include/crow/app.h | 22 ++++++++++++++++++++-- 2 files changed, 32 insertions(+), 7 deletions(-) diff --git a/include/crow/TinySHA1.hpp b/include/crow/TinySHA1.hpp index fa679307d..ff46ffbe9 100644 --- a/include/crow/TinySHA1.hpp +++ b/include/crow/TinySHA1.hpp @@ -1,8 +1,4 @@ -/* - * \file TinySHA1.hpp - * \brief TinySHA1 - a header only implementation of the SHA1 algorithm in C++. Based - * on the implementation in boost::uuid::details. - * +/* * SHA1 Wikipedia Page: http://en.wikipedia.org/wiki/SHA-1 * * Copyright (c) 2012-22 SAURAV MOHAPATRA @@ -19,6 +15,17 @@ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ + +/** + * \file TinySHA1.hpp + * \author SAURAV MOHAPATRA + * \date 2012-22 + * \brief TinySHA1 - a header only implementation of the SHA1 algorithm in C++. Based + * on the implementation in boost::uuid::details. + * + * In this file are defined: + * - sha1::SHA1 + */ #ifndef _TINY_SHA1_HPP_ #define _TINY_SHA1_HPP_ #include diff --git a/include/crow/app.h b/include/crow/app.h index 24a4a4181..3904507f6 100644 --- a/include/crow/app.h +++ b/include/crow/app.h @@ -1,3 +1,20 @@ +/** + * \file crow/app.h + * \brief This file includes the definition of the crow::Crow class, + * the crow::App and crow::SimpleApp aliases, and some macros. + * + * In this file are defined: + * - crow::Crow + * - crow::App + * - crow::SimpleApp + * - \ref CROW_ROUTE + * - \ref CROW_BP_ROUTE + * - \ref CROW_WEBSOCKET_ROUTE + * - \ref CROW_MIDDLEWARES + * - \ref CROW_CATCHALL_ROUTE + * - \ref CROW_BP_CATCHALL_ROUTE + */ + #pragma once #include @@ -56,8 +73,9 @@ * \def CROW_BP_ROUTE(blueprint, url) * \brief Creates a route for a blueprint using a rule. * - * It may use crow::Blueprint::new_rule_dynamic or crow::Blueprint::new_rule_tagged - * to define a new rule for an given blueprint. It's usage is similar + * It may use crow::Blueprint::new_rule_dynamic or + * crow::Blueprint::new_rule_tagged to define a new rule for + * an given blueprint. It's usage is similar * to CROW_ROUTE macro: * * ```cpp From 312db8ea74d8a30db0f5d634b99f21e5baa54ec0 Mon Sep 17 00:00:00 2001 From: Nabzokek Date: Mon, 22 Apr 2024 10:51:53 -0400 Subject: [PATCH 4/6] Ready to Git Pull --- Doxyfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doxyfile b/Doxyfile index b4e37870b..33fe03bc8 100644 --- a/Doxyfile +++ b/Doxyfile @@ -499,7 +499,7 @@ NUM_PROC_THREADS = 1 # normally produced when WARNINGS is set to YES. # The default value is: NO. -EXTRACT_ALL = YES # DEBUG +EXTRACT_ALL = NO # If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will # be included in the documentation. From 85cfdac21f31a1a1eb8570d9d8f588a72b3879ba Mon Sep 17 00:00:00 2001 From: Nabzokek Date: Mon, 22 Apr 2024 15:33:40 -0400 Subject: [PATCH 5/6] Removed unnecessary "TODO"s in documentation comments --- include/crow/app.h | 23 +++-------------------- include/crow/compression.h | 4 ---- include/crow/json.h | 4 ---- include/crow/middleware.h | 4 ---- 4 files changed, 3 insertions(+), 32 deletions(-) diff --git a/include/crow/app.h b/include/crow/app.h index 3904507f6..72293962b 100644 --- a/include/crow/app.h +++ b/include/crow/app.h @@ -287,21 +287,18 @@ namespace crow return max_payload_; } - /// \brief (TODO) self_t& signal_clear() { signals_.clear(); return *this; } - /// \brief (TODO) self_t& signal_add(int signal_number) { signals_.push_back(signal_number); return *this; } - /// \brief (TODO) std::vector signals() { return signals_; @@ -397,7 +394,7 @@ namespace crow return res_stream_threshold_; } - /// \brief (TODO) + self_t& register_blueprint(Blueprint& blueprint) { router_.register_blueprint(blueprint); @@ -416,7 +413,6 @@ namespace crow return *this; } - /// \brief (TODO) std::function& exception_handler() { return router_.exception_handler(); @@ -432,7 +428,7 @@ namespace crow } #ifdef CROW_ENABLE_COMPRESSION - /// \brief (TODO) + self_t& use_compression(compression::algorithm algorithm) { comp_algorithm_ = algorithm; @@ -440,13 +436,11 @@ namespace crow return *this; } - /// \brief (TODO) compression::algorithm compression_algorithm() { return comp_algorithm_; } - /// \brief (TODO) bool compression_used() const { return compression_used_; @@ -565,13 +559,11 @@ namespace crow } } - /// \brief (TODO) void add_websocket(crow::websocket::connection* conn) { websockets_.push_back(conn); } - /// \brief (TODO) void remove_websocket(crow::websocket::connection* conn) { websockets_.erase(std::remove(websockets_.begin(), websockets_.end(), conn), websockets_.end()); @@ -625,7 +617,6 @@ namespace crow return *this; } - /// \brief (TODO) self_t& ssl(asio::ssl::context&& ctx) { ssl_used_ = true; @@ -633,13 +624,12 @@ namespace crow return *this; } - /// \brief (TODO) bool ssl_used() const { return ssl_used_; } #else - /// \brief (TODO) + template self_t& ssl_file(T&&, Remain&&...) { @@ -651,7 +641,6 @@ namespace crow return *this; } - /// \brief (TODO) template self_t& ssl_chainfile(T&&, Remain&&...) { @@ -663,7 +652,6 @@ namespace crow return *this; } - /// \brief (TODO) template self_t& ssl(T&&) { @@ -675,7 +663,6 @@ namespace crow return *this; } - /// \brief (TODO) bool ssl_used() const { return false; @@ -693,7 +680,6 @@ namespace crow return ctx.template get(); } - /// \brief (TODO) template T& get_middleware() { @@ -717,7 +703,6 @@ namespace crow } private: - /// \brief TODO (But it's not so necessary). template std::tuple make_middleware_tuple(Ts&&... ts) { @@ -735,12 +720,10 @@ namespace crow cv_started_.notify_all(); } - /// \brief TODO (But it's not so necessary). void set_static_routes_added() { static_routes_added_ = true; } - /// \brief TODO (But it's not so necessary). bool are_static_routes_added() { return static_routes_added_; } diff --git a/include/crow/compression.h b/include/crow/compression.h index 518bc8163..5cac29934 100644 --- a/include/crow/compression.h +++ b/include/crow/compression.h @@ -7,10 +7,6 @@ // http://zlib.net/manual.html namespace crow // NOTE: Already documented in "crow/app.h" { - /** - * \namespace crow::compression - * \brief TODO - */ namespace compression { // Values used in the 'windowBits' parameter for deflateInit2. diff --git a/include/crow/json.h b/include/crow/json.h index cfd9464ca..dbb05e0fb 100644 --- a/include/crow/json.h +++ b/include/crow/json.h @@ -32,10 +32,6 @@ namespace crow // NOTE: Already documented in "crow/app.h" class template_t; } - /** - * \namespace crow::json - * \brief TODO - */ namespace json { inline void escape(const std::string& str, std::string& ret) diff --git a/include/crow/middleware.h b/include/crow/middleware.h index f241b1fb8..9aa71783a 100644 --- a/include/crow/middleware.h +++ b/include/crow/middleware.h @@ -18,10 +18,6 @@ namespace crow // NOTE: Already documented in "crow/app.h" using call_global = std::false_type; }; - /** - * \namespace crow::detail - * \brief TODO - */ namespace detail { template From e93d3974b6fc50cc830f43d766f5cb6601d6febe Mon Sep 17 00:00:00 2001 From: gittiver Date: Wed, 24 Apr 2024 22:27:06 +0200 Subject: [PATCH 6/6] Update app.h --- include/crow/app.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/crow/app.h b/include/crow/app.h index 72293962b..0b2d9c333 100644 --- a/include/crow/app.h +++ b/include/crow/app.h @@ -44,8 +44,8 @@ #ifdef CROW_MSVC_WORKAROUND -#define CROW_ROUTE(app, url) app.route_dynamic(url) // See the documentation in the comment bellow. -#define CROW_BP_ROUTE(blueprint, url) blueprint.new_rule_dynamic(url) // See the documentation in the comment bellow. +#define CROW_ROUTE(app, url) app.route_dynamic(url) // See the documentation in the comment below. +#define CROW_BP_ROUTE(blueprint, url) blueprint.new_rule_dynamic(url) // See the documentation in the comment below. #else // #ifdef CROW_MSVC_WORKAROUND