From f44a799c9080dbb2a0b44db4b344ac4d5fa920c1 Mon Sep 17 00:00:00 2001
From: Ernest Zaslavsky <ernest.zaslavsky@scylladb.com>
Date: Tue, 10 Sep 2024 15:25:45 +0300
Subject: [PATCH] http: clarify the ownership in the router's doxygen comment

Emphasize pointer ownership and deletion responsibility for each of methods which work with raw pointers

Closes scylladb/seastar#2423
---
 include/seastar/http/routes.hh | 21 ++++++++++++++++-----
 1 file changed, 16 insertions(+), 5 deletions(-)

diff --git a/include/seastar/http/routes.hh b/include/seastar/http/routes.hh
index 1ab8a78289f..d97283e7dfc 100644
--- a/include/seastar/http/routes.hh
+++ b/include/seastar/http/routes.hh
@@ -74,7 +74,7 @@ struct path_description;
 /**
  * routes object do the request dispatching according to the url.
  * It uses two decision mechanism exact match, if a url matches exactly
- * (an optional leading slash is permitted) it is choosen
+ * (an optional leading slash is permitted) it is chosen
  * If not, the matching rules are used.
  * matching rules are evaluated by their insertion order
  */
@@ -89,7 +89,11 @@ public:
      * adding a handler as an exact match
      * @param url the url to match (note that url should start with /)
      * @param handler the desire handler
-     * @return it self
+     * @return itself
+     * @attention If successful, this method takes ownership of the handler
+        pointer. It will be automatically deleted when the routes instance is
+        destroyed. However, if the method throws, the caller is responsible
+        for deleting the handler pointer.
      */
     routes& put(operation_type type, const sstring& url, handler_base* handler);
 
@@ -107,7 +111,9 @@ public:
      * First in higher priority
      * @param rule a rule to add
      * @param type the operation type
-     * @return it self
+     * @return itself
+     * @attention This method takes ownership of the match_rule pointer. It will be automatically deleted when the
+     * routes instance is destroyed.
      */
     routes& add(match_rule* rule, operation_type type = GET) {
         _rules[type][_rover++] = rule;
@@ -121,6 +127,8 @@ public:
      * @param url
      * @param handler
      * @return
+     * @attention This method takes ownership of the handler's pointer.It will be automatically deleted when the routes
+     * instance is destroyed.
      */
     routes& add(operation_type type, const url& url, handler_base* handler);
 
@@ -129,6 +137,7 @@ public:
      * Example  routes.add_default_handler(handler);
      * @param handler
      * @return
+     * @attention The caller must keep the @c handler active as long as the route instance is active.
      */
     routes& add_default_handler(handler_base* handler);
 
@@ -137,7 +146,7 @@ public:
      * the general handler calls this method with the request
      * the method takes the headers from the request and find the
      * right handler.
-     * It then call the handler with the parameters (if they exists) found in the url
+     * It then calls the handler with the parameters (if they exist) found in the url
      * @param path the url path found
      * @param req the http request
      * @param rep the http reply
@@ -169,7 +178,6 @@ private:
      * Normalize the url to remove the last / if exists
      * and get the parameter part
      * @param url the full url path
-     * @param param_part will hold the string with the parameters
      * @return the url from the request without the last /
      */
     sstring normalize_url(const sstring& url);
@@ -225,6 +233,8 @@ public:
      * @param rule a rule to add
      * @param type the operation type
      * @return a cookie using which the rule can be removed
+     * @attention This method takes ownership of the match_rule pointer. It will be automatically deleted when the
+     * routes instance is destroyed.
      */
     rule_cookie add_cookie(match_rule* rule, operation_type type) {
         auto pos = _rover++;
@@ -237,6 +247,7 @@ public:
      * @param cookie a cookie returned previously by add_cookie
      * @param type the operation type
      * @return the pointer to the rule
+     * @attention Ownership of the pointer is returned to the caller.
      */
     match_rule* del_cookie(rule_cookie cookie, operation_type type);
 };