add doxygen

Author: GaspardKirira

include/vix/middleware/app/adapter.hpp

@@ -23,7 +23,11 @@
 
 namespace vix::middleware::app
 {
-  // Adapt legacy HttpMiddleware(Request&, Response&, Next)
+  /**
+   * @brief Adapt a legacy HttpMiddleware to an App middleware.
+   *
+   * Converts (Request&, Response&, Next) into App::Middleware.
+   */
   inline vix::App::Middleware adapt(vix::middleware::HttpMiddleware inner)
   {
     return [inner = std::move(inner)](
@@ -36,7 +40,11 @@ namespace vix::middleware::app
     };
   }
 
-  // Adapt Context-based middleware (MiddlewareFn(Context&, Next))
+  /**
+   * @brief Adapt a Context-based middleware to an App middleware.
+   *
+   * Wraps (Context&, Next) and creates a Context instance per request.
+   */
   inline vix::App::Middleware adapt_ctx(vix::middleware::MiddlewareFn inner)
   {
     return [inner = std::move(inner),
@@ -51,6 +59,13 @@ namespace vix::middleware::app
     };
   }
 
+  /**
+   * @brief Conditionally apply a middleware based on a request predicate.
+   *
+   * @tparam Pred Callable predicate taking (const Request&) and returning bool.
+   * @param pred Predicate to decide whether to run the middleware.
+   * @param mw Middleware to run when predicate matches.
+   */
   template <class Pred>
   inline vix::App::Middleware when(Pred pred, vix::App::Middleware mw)
   {
@@ -69,9 +84,10 @@ namespace vix::middleware::app
     };
   }
 
-  inline vix::App::Middleware protect_path(
-      std::string path,
-      vix::App::Middleware mw)
+  /**
+   * @brief Apply a middleware only for an exact path.
+   */
+  inline vix::App::Middleware protect_path(std::string path, vix::App::Middleware mw)
   {
     return when(
         [path = std::move(path)](const vix::vhttp::Request &req)
@@ -81,9 +97,10 @@ namespace vix::middleware::app
         std::move(mw));
   }
 
-  inline vix::App::Middleware protect_prefix_mw(
-      std::string prefix,
-      vix::App::Middleware mw)
+  /**
+   * @brief Apply a middleware only for a path prefix.
+   */
+  inline vix::App::Middleware protect_prefix_mw(std::string prefix, vix::App::Middleware mw)
   {
     return when(
         [prefix = std::move(prefix)](const vix::vhttp::Request &req)
@@ -93,31 +110,38 @@ namespace vix::middleware::app
         std::move(mw));
   }
 
-  inline void protect(
-      vix::App &app,
-      std::string exact_path,
-      vix::App::Middleware mw)
+  /**
+   * @brief Install a middleware that applies only to an exact path.
+   */
+  inline void protect(vix::App &app, std::string exact_path, vix::App::Middleware mw)
   {
     app.use(protect_path(std::move(exact_path), std::move(mw)));
   }
 
-  inline void protect_prefix(
-      vix::App &app,
-      std::string prefix,
-      vix::App::Middleware mw)
+  /**
+   * @brief Install a middleware that applies only to a path prefix.
+   */
+  inline void protect_prefix(vix::App &app, std::string prefix, vix::App::Middleware mw)
   {
     app.use(protect_prefix_mw(std::move(prefix), std::move(mw)));
   }
 
+  /**
+   * @brief Install a middleware on a route prefix (App::use(prefix, mw)).
+   */
   inline void install(vix::App &app, std::string prefix, vix::App::Middleware mw)
   {
     app.use(std::move(prefix), std::move(mw));
   }
 
+  /**
+   * @brief Install a middleware on an exact path (alias of protect()).
+   */
   inline void install_exact(vix::App &app, std::string exact_path, vix::App::Middleware mw)
   {
     protect(app, std::move(exact_path), std::move(mw));
   }
-}
 
-#endif
+} // namespace vix::middleware::app
+
+#endif // VIX_ADAPTER_HPP

include/vix/middleware/app/app_middleware.hpp

@@ -22,19 +22,37 @@
 
 namespace vix::middleware::app
 {
+  /** @brief Alias for the HTTP cache app configuration. */
   using HttpCacheConfig = HttpCacheAppConfig;
 
+  /**
+   * @brief Build an HTTP cache middleware for App (prefix is ignored).
+   *
+   * @param cfg Cache configuration (prefix is cleared).
+   * @return App middleware.
+   */
   inline vix::App::Middleware http_cache(HttpCacheConfig cfg = {})
   {
     cfg.prefix.clear();
     return http_cache_mw(std::move(cfg));
   }
 
+  /**
+   * @brief Install the HTTP cache middleware on an app prefix.
+   *
+   * @param app Target application.
+   * @param cfg Cache configuration (uses cfg.prefix).
+   */
   inline void use_http_cache(vix::App &app, HttpCacheConfig cfg = {})
   {
     vix::middleware::app::install_http_cache(app, std::move(cfg));
   }
 
+  /**
+   * @brief Chain multiple App middlewares in order.
+   *
+   * Each middleware must call the provided Next to continue.
+   */
   inline vix::App::Middleware chain(std::vector<vix::App::Middleware> mws)
   {
     return [mws = std::move(mws)](
@@ -61,16 +79,22 @@ namespace vix::middleware::app
     };
   }
 
+  /**
+   * @brief Chain two App middlewares.
+   */
   inline vix::App::Middleware chain(vix::App::Middleware a, vix::App::Middleware b)
   {
     return chain(std::vector<vix::App::Middleware>{std::move(a), std::move(b)});
   }
 
+  /**
+   * @brief Chain three App middlewares.
+   */
   inline vix::App::Middleware chain(vix::App::Middleware a, vix::App::Middleware b, vix::App::Middleware c)
   {
     return chain(std::vector<vix::App::Middleware>{std::move(a), std::move(b), std::move(c)});
   }
 
 } // namespace vix::middleware::app
 
-#endif
+#endif // VIX_APP_MIDDLEWARE_HPP

include/vix/middleware/app/http_cache.hpp

@@ -27,6 +27,9 @@
 
 namespace vix::middleware::app
 {
+  /**
+   * @brief Configuration for installing the HTTP cache middleware in an App.
+   */
   struct HttpCacheAppConfig
   {
     std::string prefix{"/api/"};
@@ -44,6 +47,12 @@ namespace vix::middleware::app
     std::string debug_header{"x-vix-cache-status"};
   };
 
+  /**
+   * @brief Create a default in-memory cache instance from app config.
+   *
+   * @param cfg App-level cache configuration.
+   * @return Shared cache instance.
+   */
   inline std::shared_ptr<vix::cache::Cache>
   make_default_cache(const HttpCacheAppConfig &cfg)
   {
@@ -54,6 +63,12 @@ namespace vix::middleware::app
     return std::make_shared<vix::cache::Cache>(policy, store);
   }
 
+  /**
+   * @brief Build an App middleware that caches HTTP responses.
+   *
+   * @param cfg App-level cache configuration.
+   * @return App middleware.
+   */
   inline vix::App::Middleware http_cache_mw(HttpCacheAppConfig cfg = {})
   {
     auto cache = cfg.cache ? std::move(cfg.cache) : make_default_cache(cfg);
@@ -78,6 +93,12 @@ namespace vix::middleware::app
     return mw;
   }
 
+  /**
+   * @brief Install the HTTP cache middleware on an app prefix.
+   *
+   * @param app Target application.
+   * @param cfg App-level cache configuration.
+   */
   inline void install_http_cache(vix::App &app, HttpCacheAppConfig cfg = {})
   {
     std::string prefix = cfg.prefix;
@@ -89,4 +110,4 @@ namespace vix::middleware::app
 
 } // namespace vix::middleware::app
 
-#endif
+#endif // VIX_HTTP_CACHE_HPP