kwargs are typed as Incomplete

[symeneses]

Numpydoc style guide recommends to leave **kwargs without types.

When documenting variable length positional, or keyword arguments, leave the leading star(s) in front of the name and do not specify a type.

The Incomplete type is wrong in this case as it's not a missing or partial annoation as by standard it shouldn't have a type.

[OriolAbril]

I would be nice to check if an argument starts with asterisk or double asterisk and in those cases use Any if the type is missing instead of Incomplete. I only considered the case where we do want to add the type of *args or **kwargs explicitly in #39, not the default case where no type info is given in the docstring.

[lagru]

@symeneses, I think I based the current behavior on Python's typing documentation

At runtime, the type of a variadic positional parameter (*args) is a tuple, and the type of a variadic keyword parameter (**kwargs) is a dict. However, when annotating these parameters, the type annotation refers to the type of items within the tuple or dict (unless Unpack is used).

So in this case I gave the above priority over what the current NumPyDoc style guide recommends. Since Python's type system supports annotating *args and **kwargs – and type checkers may require it – I think docstub should support this case. And if the user doesn't specify it, docstub should fall back to Incomplete as it does for all cases where the docstring is lacking.

Does that make sense to you? Let me also check if the behavior I describe above is actually what docstub is doing.

[lagru]

@OriolAbril, could you explain why you think Any would be more fitting as a fallback than Incomplete? The typing guide addresses this case explicitly. And the way I understand it, Any is the explicit choice that something can't be effectively typed, while Incomplete denotes something is missing – in this case from the docstring.

[OriolAbril]

I don't think following the main numpydoc recommendation on args and kwargs should be flagged as something missing or a todo still pending.

There are some cases where all args or kwargs will have the same type, and we can type them explicitly, but this is more the exception than the rule. In general they are arbitrary and inhomogeneous arguments that get forwarded somewhere else. Moreover, the "somewhere else" can be a used defined function about which we know nothing as would be the case for numpy.picewise.

I might be reading too much into it, but I think the numpydoc policy of:

When documenting variable length positional, or keyword arguments, leave the leading star(s) in front of the name and do not specify a type.

*args
    Additional arguments should be passed as keyword arguments
**kwargs
    Extra arguments to `metric`: refer to each metric documentation for a list of all possible arguments.

Is exactly for that, so docstrings don't end up doing things like kw : dict, optional which is clearly wrong (and which pointwise above does). It should be using **kw instead. The leading ** indicates it is arbitrary length, arbitrary keyword and arbitrary value arguments. It also makes optional redundant.

Still, even if reading too much into it, it seems wrong to have some of the very few examples on the numpydoc style guide itself be parsed as incomplete.