Skip to content

Commit

Permalink
DOC: Do not use types for *args, **kwargs (#585)
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
timhoffm authored Oct 17, 2024
1 parent 1338660 commit 2af51f7
Showing 1 changed file with 3 additions and 3 deletions.
6 changes: 3 additions & 3 deletions doc/format.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down

0 comments on commit 2af51f7

Please sign in to comment.