From 2af51f711c8610a86678f05543e19ca1b6f97853 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Thu, 17 Oct 2024 16:27:03 +0200
Subject: [PATCH] DOC: Do not use types for *args, **kwargs (#585)

Docstrings are primarily intended for the caller, and there *args, **kwargs are not variables with a type but a signature pattern (this is also hinted at by using *args, **kwargs instead of args, kwargs as parameter names). It's rather confusing to try and type them, I'd even claim it's misleading and will tempt less experienced programmers to call `def func(*args)` with *args declared as tuple with a single tuple argument `func((1, 2, 3))`.

This omission is also not an information loss for the few people, who look at the signature from the function body perspective (aka developers). That args and kwargs resolve to a tuple / dict in the function is a hard-coded fact.
---
 doc/format.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/format.rst b/doc/format.rst
index 92cc2d36..6579191c 100644
--- a/doc/format.rst
+++ b/doc/format.rst
@@ -225,11 +225,11 @@ description, they can be combined::
       Input arrays, description of `x1`, `x2`.
 
 When documenting variable length positional, or keyword arguments, leave the
-leading star(s) in front of the name::
+leading star(s) in front of the name and do not specify a type::
 
-  *args : tuple
+  *args
       Additional arguments should be passed as keyword arguments
-  **kwargs : dict, optional
+  **kwargs
       Extra arguments to `metric`: refer to each metric documentation for a
       list of all possible arguments.