[doc] Add an example for 'too-many-locals' (#8306)

5 files changed, 80 insertions, 6 deletions

diff --git a/doc/data/messages/t/too-many-locals/bad.py b/doc/data/messages/t/too-many-locals/bad.py
new file mode 100644
index 000000000..dae054ed8
--- /dev/null
+++ b/doc/data/messages/t/too-many-locals/bad.py
@@ -0,0 +1,27 @@
+from childhood import Child, Sweet
+
+
+def handle_sweets(infos):  # [too-many-locals]
+    # Create children
+    children = [Child(info) for info in infos]
+    number_of_sweets = 87
+    sweets = [Sweet() * number_of_sweets]
+    number_of_sweet_per_child = 5
+    money = 45.0
+    sweets_given = 0
+    time_to_eat_sweet = 54
+    price_of_sweet = 0.42
+    # distribute sweet
+    for child in children:
+        sweets_given += number_of_sweet_per_child
+        child.give(sweets[number_of_sweet_per_child:])
+    # calculate prices
+    cost_of_children = sweets_given * price_of_sweet
+    # Calculate remaining money
+    remaining_money = money - cost_of_children
+    # Calculate time it took
+    time_it_took_assuming_parallel_eating = time_to_eat_sweet * number_of_sweet_per_child
+    print(
+        f"{children} ate {cost_of_children}¤ of sweets in {time_it_took_assuming_parallel_eating}, "
+        f"you still have {remaining_money}"
+    )
diff --git a/doc/data/messages/t/too-many-locals/details.rst b/doc/data/messages/t/too-many-locals/details.rst
index ab8204529..08de9cbc5 100644
--- a/doc/data/messages/t/too-many-locals/details.rst
+++ b/doc/data/messages/t/too-many-locals/details.rst
@@ -1 +1,3 @@
-You can help us make the doc better `by contributing <https://github.com/PyCQA/pylint/issues/5953>`_ !
+Having too many locals may indicate that you're doing too much in a function and that
+classes regrouping some attributes could be created. Maybe operations could be separated in
+multiple functions. Are all your variables really closely related ?
diff --git a/doc/data/messages/t/too-many-locals/good.py b/doc/data/messages/t/too-many-locals/good.py
index c40beb573..c1e74200a 100644
--- a/doc/data/messages/t/too-many-locals/good.py
+++ b/doc/data/messages/t/too-many-locals/good.py
@@ -1 +1,44 @@
-# This is a placeholder for correct code for this message.
+from typing import NamedTuple
+
+from childhood import Child, Sweet
+
+
+class SweetDistrubutionCharacteristics(NamedTuple):
+    number_of_sweets: int
+    number_of_sweet_per_child: int
+    number_of_children: int
+
+    @property
+    def sweets_given(self):
+        return self.number_of_sweet_per_child * self.number_of_children
+
+
+def handle_sweets(infos):
+    children = [Child(info) for info in infos]
+    characteristics = SweetDistrubutionCharacteristics(87, 5, len(children))
+    _allocate_sweets_to_children(children, characteristics)
+    financial_impact = _assess_financial_impact(characteristics)
+    print(f"{children} ate {financial_impact}")
+
+
+def _allocate_sweets_to_children(
+    children, characteristics: SweetDistrubutionCharacteristics
+) -> None:
+    sweets = [Sweet() * characteristics.number_of_sweets]
+    for child in children:
+        child.give(sweets[characteristics.number_of_sweet_per_child :])
+
+
+def _assess_financial_impact(characteristics: SweetDistrubutionCharacteristics) -> str:
+    time_to_eat_sweet = 54
+    money = 45.0
+    price_of_sweet = 0.42
+    cost_of_children = characteristics.sweets_given * price_of_sweet
+    remaining_money = money - cost_of_children
+    time_it_took_assuming_parallel_eating = (
+        time_to_eat_sweet * characteristics.number_of_sweet_per_child
+    )
+    return (
+        f"{cost_of_children}¤ of sweets in "
+        f"{time_it_took_assuming_parallel_eating}, you still have {remaining_money}"
+    )
diff --git a/doc/data/messages/t/too-many-locals/pylintrc b/doc/data/messages/t/too-many-locals/pylintrc
new file mode 100644
index 000000000..cf4e92d2b
--- /dev/null
+++ b/doc/data/messages/t/too-many-locals/pylintrc
@@ -0,0 +1,2 @@
+[design]
+max-locals = 11
diff --git a/tests/functional/t/too/too_many_locals.py b/tests/functional/t/too/too_many_locals.py
index cd37e53cb..34395871d 100644
--- a/tests/functional/t/too/too_many_locals.py
+++ b/tests/functional/t/too/too_many_locals.py
@@ -10,7 +10,7 @@ def function(arg1, arg2, arg3, arg4, arg5): # [too-many-locals]
 
 
 def too_many_locals_function(): # [too-many-locals]
-    """pylint will complains about too many local variables"""
+    """pylint will complain about too many local variables"""
     args0 = 0
     args1 = args0 * 1
     args2 = args1 * 2
@@ -30,7 +30,7 @@ def too_many_locals_function(): # [too-many-locals]
     return args15
 
 def too_many_arguments_function(arga, argu, argi, arge, argt, args): # [too-many-arguments]
-    """pylint will complains about too many arguments."""
+    """pylint will complain about too many arguments."""
     arga = argu
     arga += argi
     arga += arge
@@ -42,7 +42,7 @@ def ignored_arguments_function(arga, argu, argi,
                                _arge=0, _argt=1, _args=None):
     """pylint will ignore _arge, _argt, _args.
 
-    Consequently pylint will only coun 13 arguments.
+    Consequently, pylint will only count 13 arguments.
     """
     arg0 = 0
     arg1 = arg0 * 1 + arga
@@ -62,7 +62,7 @@ def ignored_arguments_function(arga, argu, argi,
 def ignored_locals_function():
     """pylint will ignore '_' (an underscore) as a local variable.
 
-    Consequently pylint will only count 15 local variables.
+    Consequently, pylint will only count 15 local variables.
     """
 
     args0 = 0