Extend documentation for redefined-builtin (#10167)

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.

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]

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

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