From e5acb031373a041269a8bb47a26a9f6c593b91f0 Mon Sep 17 00:00:00 2001
From: Aurelien DARRAGON <adarragon@haproxy.com>
Date: Thu, 28 Nov 2024 17:39:00 +0100
Subject: [PATCH] DOC: lua: prefer Patref:{set,add}() over legacy methods for
 acl and maps

Patref:set() can achieve the same thing as core.set_map()
Patref:add() can achieve the same thing as core.add_acl()
Patref:del() can achieve the same thing as core.del_map() and
core.del_acl()

As a bonus, Patref:{set,add} are more efficient than their core
legacy equivalent, because they don't require systematic pattern
reference lookup for each individual operation.

Let's mention that in the doc to encourage Patref methods adoption.
---
 doc/lua-api/index.rst | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/doc/lua-api/index.rst b/doc/lua-api/index.rst
index 6ca26c737..c16a07e6c 100644
--- a/doc/lua-api/index.rst
+++ b/doc/lua-api/index.rst
@@ -360,6 +360,8 @@ Core class
 
 .. js:function:: core.add_acl(name, key)
 
+  **LEGACY**
+
   **context**: init, task, action, sample-fetch, converter
 
   Add the ACL *key* in the ACLs list referenced by *name*.
@@ -367,8 +369,14 @@ Core class
   :param string name: the name that reference the ACL entries.
   :param string key: the key which will be added.
 
+  .. Note::
+     This function is not optimal due to systematic Map reference lookup.
+     It is recommended to use :js:func:`Patref.add()` instead.
+
 .. js:function:: core.del_acl(name, key)
 
+  **LEGACY**
+
   **context**: init, task, action, sample-fetch, converter
 
   Delete the ACL entry referenced by the key *key* in the list of ACLs
@@ -377,8 +385,14 @@ Core class
   :param string name: the name that reference the ACL entries.
   :param string key: the key which will be deleted.
 
+  .. Note::
+     This function is not optimal due to systematic Map reference lookup.
+     It is recommended to use :js:func:`Patref.del()` instead.
+
 .. js:function:: core.del_map(name, key)
 
+  **LEGACY**
+
   **context**: init, task, action, sample-fetch, converter
 
   Delete the map entry indexed with the specified key in the list of maps
@@ -387,6 +401,10 @@ Core class
   :param string name: the name that reference the map entries.
   :param string key: the key which will be deleted.
 
+  .. Note::
+     This function is not optimal due to systematic Map reference lookup.
+     It is recommended to use :js:func:`Patref.del()` instead.
+
 .. js:function:: core.get_info()
 
   **context**: body, init, task, action, sample-fetch, converter
@@ -840,6 +858,8 @@ Core class
 
 .. js:function:: core.set_map(name, key, value)
 
+  **LEGACY**
+
   **context**: init, task, action, sample-fetch, converter
 
   Set the value *value* associated to the key *key* in the map referenced by
@@ -849,6 +869,10 @@ Core class
   :param string key: the key to set or replace
   :param string value: the associated value
 
+  .. Note::
+     This function is not optimal due to systematic Map reference lookup.
+     It is recommended to use :js:func:`Patref.set()` instead.
+
 .. js:function:: core.sleep(int seconds)
 
   **context**: task, action