*args and **kwargs annotations not matched properly

[anentropic]

this should work:

def myfunc(regular_arg, **kwargs):
    """
    Args:
        regular_arg (str)
        **kwargs
    """

...but gives "arg names which are inconsistent with the function signature" error

[anentropic]

At the moment I think **kwargs is broken by a bug

But also... Napoleon examples don't show how to type-annotate the kwargs: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html#example-google

Whereas mypy allows: https://mypy.readthedocs.io/en/stable/cheat_sheet.html#when-you-re-puzzled-or-when-things-are-complicated

So we should be able to parse this:

def myfunc(regular_arg, **kwargs):
    """
    Args:
        regular_arg (str)
        **kwargs (str)
    """

as:

def myfunc(regular_arg: str, **kwargs: str):
    # type: (str, **str) -> None
    """
    Args:
        regular_arg
        **kwargs
    """

I think in real life we have some docstrings like:

def myfunc(regular_arg, **kwargs):
    """
    Args:
        regular_arg (str)
        **kwargs (Dict[str, str])
    """

intending the same meaning... but for now I don't propose to handle that.

Perhaps we should optionally raise a warning if the **kwargs type is a Dict[str, ...] or the *args type is a Tuple(...) as it may mean they were annotated without understanding the format chosen by mypy.

[anentropic]

This code is already over-complicated, so I am going to skip the optional warning. Type-checker will find the inconsistencies so you can fix them in the checkable annotations.

Similarly I think we will have a bunch of functions taking *args / **kwargs where they are omitted from the Args section of the docstring or given without types. We might interpret that as an implicit *Any / **Any.

But it's easier to just let them come up as either "arg names which are inconsistent with the function signature" error (when omitted) or "did not fully specify arg types" (when un-typed)