[too-many-positional-arguments] Better documentation following questions (#10049)

* [too-many-positional-arguments] Better documentation following questions

See https://github.com/astral-sh/ruff/issues/8946\#issuecomment-2437547742

Co-authored-by: Philipp Albrecht <[email protected]>

* Apply suggestions from code review

Co-authored-by: Jacob Walls <[email protected]>

---------

Co-authored-by: Philipp Albrecht <[email protected]>
Co-authored-by: Jacob Walls <[email protected]>

Author: 3 people

doc/data/messages/t/too-many-positional-arguments/bad.py

@@ -1,5 +1,6 @@
 # +1: [too-many-positional-arguments]
 def calculate_drag_force(velocity, area, density, drag_coefficient):
+    """Each argument is positional-or-keyword unless a `/` or `*` is present."""
     return 0.5 * drag_coefficient * density * area * velocity**2
 
 

doc/data/messages/t/too-many-positional-arguments/details.rst

@@ -1,10 +1,11 @@
-Positional arguments work well for cases where the the use cases are
-self-evident, such as unittest's ``assertEqual(first, second, msg=None)``.
-Comprehensibility suffers beyond a handful of arguments, though, so for
-functions that take more inputs, require that additional arguments be
-passed by *keyword only* by preceding them with ``*``:
+Good function signatures don’t have many positional parameters. For almost all
+interfaces, comprehensibility suffers beyond a handful of arguments.
 
-.. code-block:: python
+Positional arguments work well for cases where the the use cases are
+self-evident, such as unittest's ``assertEqual(first, second, "assert msg")``
+or ``zip(fruits, vegetables)``.
 
-    def make_noise(self, volume, *, color=noise.PINK, debug=True):
-        ...
+There are a few exceptions where four or more positional parameters make sense,
+for example ``rgba(1.0, 0.5, 0.3, 1.0)``, because it uses a very well-known and
+well-established convention, and using keywords all the time would be a waste
+of time.

doc/data/messages/t/too-many-positional-arguments/good.py

@@ -1,7 +1,14 @@
 def calculate_drag_force(*, velocity, area, density, drag_coefficient):
+    """This function is 'Keyword only' for all args due to the '*'."""
     return 0.5 * drag_coefficient * density * area * velocity**2
 
 
+# This is now impossible to do and will raise a TypeError:
+# drag_force = calculate_drag_force(30, 2.5, 1.225, 0.47)
+#              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+# TypeError: calculate_drag_force() takes 0 positional arguments but 4 were given
+
+# And this is the only way to call 'calculate_drag_force'
 drag_force = calculate_drag_force(
     velocity=30, area=2.5, density=1.225, drag_coefficient=0.47
 )

doc/data/messages/t/too-many-positional-arguments/related.rst

@@ -1,2 +1 @@
-- `Ruff discussion <https://github.com/astral-sh/ruff/issues/8946>`_
-- `Pylint issue <https://github.com/pylint-dev/pylint/issues/9099>`_
+- `Special parameters in python <https://docs.python.org/3/tutorial/controlflow.html#special-parameters>`_