From 054f23363fd50efedaf54ee7fb0333824b0de41f Mon Sep 17 00:00:00 2001
From: Zen Lee <53538590+zenlyj@users.noreply.github.com>
Date: Sat, 4 Jan 2025 21:58:16 +0800
Subject: [PATCH] Extend documentation for `redefined-builtin` (#10167)

---
 .../messages/r/redefined-builtin/details.rst  | 22 +++++++++++++++++++
 .../r/redefined/redefined_builtin_allowed.py  |  5 +++++
 .../r/redefined/redefined_builtin_allowed.rc  |  4 ++--
 .../r/redefined/redefined_builtin_allowed.txt |  1 +
 4 files changed, 30 insertions(+), 2 deletions(-)
 create mode 100644 doc/data/messages/r/redefined-builtin/details.rst

diff --git a/doc/data/messages/r/redefined-builtin/details.rst b/doc/data/messages/r/redefined-builtin/details.rst
new file mode 100644
index 0000000000..6c4ab7435c
--- /dev/null
+++ b/doc/data/messages/r/redefined-builtin/details.rst
@@ -0,0 +1,22 @@
+The :ref:`allowed-redefined-builtins <variables-options>` option lets you specify names that are permitted to shadow built-ins.
+
+However, this option is not effective for redefinitions at the module level or for global variables. For example:
+
+Module-Level Redefinitions::
+
+    # module_level_redefine.py
+    id = 1  # Shadows the built-in `id`
+
+Global Variable Redefinitions::
+
+    # global_variable_redefine.py
+    def my_func():
+        global len
+        len = 1  # Shadows the built-in `len`
+
+Rationale:
+
+Shadowing built-ins at the global scope is discouraged because it obscures their behavior
+throughout the entire module, increasing the risk of subtle bugs when the built-in is needed elsewhere.
+In contrast, local redefinitions are acceptable as their impact is confined to a specific scope,
+reducing unintended side effects and simplifying debugging.
diff --git a/tests/functional/r/redefined/redefined_builtin_allowed.py b/tests/functional/r/redefined/redefined_builtin_allowed.py
index ec7697dfce..7574b5cb5f 100644
--- a/tests/functional/r/redefined/redefined_builtin_allowed.py
+++ b/tests/functional/r/redefined/redefined_builtin_allowed.py
@@ -7,3 +7,8 @@ def function():
     print(dir, dict)
 
 list = "not in globals" # [redefined-builtin]
+
+def global_variable_redefine():
+    """Shadow `len` using the `global` keyword."""
+    global len
+    len = 1  # [redefined-builtin]
diff --git a/tests/functional/r/redefined/redefined_builtin_allowed.rc b/tests/functional/r/redefined/redefined_builtin_allowed.rc
index 845729dcee..0a255bfae3 100644
--- a/tests/functional/r/redefined/redefined_builtin_allowed.rc
+++ b/tests/functional/r/redefined/redefined_builtin_allowed.rc
@@ -1,4 +1,4 @@
 [messages control]
-disable = invalid-name
+disable = invalid-name, global-variable-undefined
 [variables]
-allowed-redefined-builtins = dir, list
+allowed-redefined-builtins = dir, list, len
diff --git a/tests/functional/r/redefined/redefined_builtin_allowed.txt b/tests/functional/r/redefined/redefined_builtin_allowed.txt
index a0a049e2fd..669cb94bfc 100644
--- a/tests/functional/r/redefined/redefined_builtin_allowed.txt
+++ b/tests/functional/r/redefined/redefined_builtin_allowed.txt
@@ -1,2 +1,3 @@
 redefined-builtin:6:4:6:8:function:Redefining built-in 'dict':UNDEFINED
 redefined-builtin:9:0:9:4::Redefining built-in 'list':UNDEFINED
+redefined-builtin:14:4:14:7:global_variable_redefine:Redefining built-in 'len':UNDEFINED