From 2efd0996e61fe82a4922224fa8c039116281d345 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lars=20M=C3=BCller?=
 <34514239+appgurueu@users.noreply.github.com>
Date: Tue, 30 Apr 2024 13:50:31 +0200
Subject: [PATCH] Document empty string as form name (#14601)

---
 doc/lua_api.md                  | 11 ++++++++---
 src/script/lua_api/l_server.cpp |  4 ++++
 2 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/doc/lua_api.md b/doc/lua_api.md
index ca09f436b..297591698 100644
--- a/doc/lua_api.md
+++ b/doc/lua_api.md
@@ -5808,8 +5808,8 @@ Call these functions only at load time!
     * Return `true` to mark the command as handled, which means that the default
       handlers will be prevented.
 * `minetest.register_on_player_receive_fields(function(player, formname, fields))`
-    * Called when the server received input from `player` in a formspec with
-      the given `formname`. Specifically, this is called on any of the
+    * Called when the server received input from `player`.
+      Specifically, this is called on any of the
       following events:
           * a button was pressed,
           * Enter was pressed while the focus was on a text field
@@ -5820,6 +5820,9 @@ Call these functions only at load time!
           * an entry was double-clicked in a textlist or table,
           * a scrollbar was moved, or
           * the form was actively closed by the player.
+    * `formname` is the name passed to `minetest.show_formspec`.
+      Special case: The empty string refers to the player inventory
+      (the formspec set by the `set_inventory_formspec` player method).
     * Fields are sent for formspec elements which define a field. `fields`
       is a table containing each formspecs element value (as string), with
       the `name` parameter as index for each. The value depends on the
@@ -6418,7 +6421,8 @@ Formspec
 * `minetest.show_formspec(playername, formname, formspec)`
     * `playername`: name of player to show formspec
     * `formname`: name passed to `on_player_receive_fields` callbacks.
-      It should follow the `"modname:<whatever>"` naming convention
+      It should follow the `"modname:<whatever>"` naming convention.
+      `formname` must not be empty.
     * `formspec`: formspec to display
 * `minetest.close_formspec(playername, formname)`
     * `playername`: name of player to close formspec
@@ -9667,6 +9671,7 @@ Used by `minetest.register_node`.
 
     on_receive_fields = function(pos, formname, fields, sender),
     -- fields = {name1 = value1, name2 = value2, ...}
+    -- formname should be the empty string; you **must not** use formname.
     -- Called when an UI form (e.g. sign text input) returns data.
     -- See minetest.register_on_player_receive_fields for more info.
     -- default: nil
diff --git a/src/script/lua_api/l_server.cpp b/src/script/lua_api/l_server.cpp
index 185287dd7..af9a526e0 100644
--- a/src/script/lua_api/l_server.cpp
+++ b/src/script/lua_api/l_server.cpp
@@ -426,6 +426,10 @@ int ModApiServer::l_show_formspec(lua_State *L)
 	NO_MAP_LOCK_REQUIRED;
 	const char *playername = luaL_checkstring(L, 1);
 	const char *formname = luaL_checkstring(L, 2);
+	if (*formname == '\0') {
+		log_deprecated(L, "Deprecated call to `minetest.show_formspec`:"
+				"`formname` must not be empty");
+	}
 	const char *formspec = luaL_checkstring(L, 3);
 
 	if(getServer(L)->showFormspec(playername,formspec,formname))