From c87600d2c720ad82c495c6780c748b6a6340afaa Mon Sep 17 00:00:00 2001
From: Pavel Semyonov <p.semyonov@vk.team>
Date: Mon, 16 Dec 2024 14:32:56 +0700
Subject: [PATCH 1/3] Add box.watch_once()

---
 doc/reference/reference_lua/box_events.rst    |  6 ++-
 .../reference_lua/box_events/watch_once.rst   | 37 +++++++++++++++++++
 2 files changed, 42 insertions(+), 1 deletion(-)
 create mode 100644 doc/reference/reference_lua/box_events/watch_once.rst

diff --git a/doc/reference/reference_lua/box_events.rst b/doc/reference/reference_lua/box_events.rst
index b6748bfb78..6d8cca7951 100644
--- a/doc/reference/reference_lua/box_events.rst
+++ b/doc/reference/reference_lua/box_events.rst
@@ -64,9 +64,12 @@ Below is a list of all functions and pages related to watchers or events.
         *   - Name
             - Use
 
-        *  - :doc:`./box_events/watch`
+        *  - :ref:`box.watch() <box-watch>`
            - Create a local watcher.
 
+        *  - :ref:`box.watch_once() <box-watch>`
+           - Create a local watcher for a single use.
+
         *  - :ref:`conn:watch() <conn-watch>`
            - Create a watcher for the remote host.
 
@@ -80,5 +83,6 @@ Below is a list of all functions and pages related to watchers or events.
     :hidden:
 
     box_events/watch
+    box_events/watch_once
     box_events/broadcast
     box_events/system_events
\ No newline at end of file
diff --git a/doc/reference/reference_lua/box_events/watch_once.rst b/doc/reference/reference_lua/box_events/watch_once.rst
new file mode 100644
index 0000000000..8a367a8598
--- /dev/null
+++ b/doc/reference/reference_lua/box_events/watch_once.rst
@@ -0,0 +1,37 @@
+.. _box-watch_once:
+
+box.watch_once()
+================
+
+..  function:: box.watch_once(key, func)
+
+    Returns the current value of a given notification key.
+    The function can be used as an alternative to :ref:`box.watch() <box-watch>`
+    for cases when the caller only needs to retrieve the current value without
+    subscribing to future changes.
+
+    :param string key: key name
+
+    :return: the key value
+
+    To read more about watchers, see the :ref:`Functions for watchers <box-watchers>` section.
+
+    **Example:**
+
+    ..  code-block:: lua
+
+        -- Broadcast value 42 for the 'foo' key.
+        box.broadcast('foo', 42)
+
+        -- Get the value of this key
+        tarantool> box.watch_once('foo')
+        ---
+        ...
+
+        -- Non-existent keys' values are empty
+        tarantool> box.watch_once('none')
+        ---
+        ...
+
+
+

From 90a41052348effee68af422576e0c9e1f663cc3c Mon Sep 17 00:00:00 2001
From: Pavel Semyonov <p.semyonov@vk.team>
Date: Mon, 16 Dec 2024 14:45:26 +0700
Subject: [PATCH 2/3] Fix

---
 doc/reference/reference_lua/box_events.rst            | 2 +-
 doc/reference/reference_lua/box_events/watch_once.rst | 5 ++---
 2 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/doc/reference/reference_lua/box_events.rst b/doc/reference/reference_lua/box_events.rst
index 6d8cca7951..0dcadf7595 100644
--- a/doc/reference/reference_lua/box_events.rst
+++ b/doc/reference/reference_lua/box_events.rst
@@ -68,7 +68,7 @@ Below is a list of all functions and pages related to watchers or events.
            - Create a local watcher.
 
         *  - :ref:`box.watch_once() <box-watch>`
-           - Create a local watcher for a single use.
+           - Get the current key value.
 
         *  - :ref:`conn:watch() <conn-watch>`
            - Create a watcher for the remote host.
diff --git a/doc/reference/reference_lua/box_events/watch_once.rst b/doc/reference/reference_lua/box_events/watch_once.rst
index 8a367a8598..b7fbca6659 100644
--- a/doc/reference/reference_lua/box_events/watch_once.rst
+++ b/doc/reference/reference_lua/box_events/watch_once.rst
@@ -7,14 +7,13 @@ box.watch_once()
 
     Returns the current value of a given notification key.
     The function can be used as an alternative to :ref:`box.watch() <box-watch>`
-    for cases when the caller only needs to retrieve the current value without
-    subscribing to future changes.
+    when the caller only needs the current value without subscribing to future changes.
 
     :param string key: key name
 
     :return: the key value
 
-    To read more about watchers, see the :ref:`Functions for watchers <box-watchers>` section.
+    To read more about watchers, see the :ref:`box-watchers` section.
 
     **Example:**
 

From 52c80f79a0d587576babe945cc6ca3d88acefcba Mon Sep 17 00:00:00 2001
From: Pavel Semyonov <p.semyonov@vk.team>
Date: Mon, 16 Dec 2024 14:51:23 +0700
Subject: [PATCH 3/3] Fix call example

---
 doc/reference/reference_lua/box_events/watch_once.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/doc/reference/reference_lua/box_events/watch_once.rst b/doc/reference/reference_lua/box_events/watch_once.rst
index b7fbca6659..361eb8cef2 100644
--- a/doc/reference/reference_lua/box_events/watch_once.rst
+++ b/doc/reference/reference_lua/box_events/watch_once.rst
@@ -25,6 +25,7 @@ box.watch_once()
         -- Get the value of this key
         tarantool> box.watch_once('foo')
         ---
+        - 42
         ...
 
         -- Non-existent keys' values are empty