search

pylint-dev / pylint

It's not just a linter that annoys you!
https://pylint.readthedocs.io/en/latest/
GNU General Public License v2.0
5.32k stars 1.14k forks source link

docparams raise missing-type-doc without missing-param-doc for Google docstrings #2483

Open AWhetter opened 6 years ago

AWhetter commented 6 years ago

Is your feature request related to a problem? Please describe

If an invalid type is detected in a Google type docstring, both missing-param-doc and missing-type-doc are raised. This is because the valid type regex fails to match, and therefore the whole parameter regex fails to match. For example:

Args:
    param (this is not a type): This is the description.

Describe the solution you'd like

Ideally missing-param-doc would not get raised in the above situation.

plelievre commented 6 years ago

Multitype arguments

It is also the case for multitype arguments, as soon as there is a " " or a "," between parenthesis.

Args:
    vector (list, np.ndarray): This is the description.
AWhetter commented 6 years ago

The proper syntax for multiple types is vector (list or np.array): This is the description.. Although Sphinx will technically work with both and it should be easy for us to include...

plelievre commented 6 years ago

Sorry, I thought that " or " was only for numpy type docstring. Actually the problem seems to be related with " " that are not around "or". According to numpy documentation, the following should be possible, but I get W9015 and W9016 error.

    Parameters
    ----------
    param : np.ndarray or tuple of np.ndarray
        This is the description.
AWhetter commented 6 years ago

Good to know. I don't think that sphinx supports that but that doesn't mean we shouldn't.