Warns section is being misinterpretted as a Raises section

[oliversheridanmethven]

I have a function which warns but does not raise. The numpy style guide has a section specifically for Warns. However, the tool is raising a DOC502 error saying that my function raises in the docstring but does not raise in the body. This is a false negative.

[jsh9]

Hi @oliversheridanmethven , could you provide a code example for me to reproduce this issue? Thanks!

[oliversheridanmethven]

The following code:

import warnings

def foo() -> None:
    """
    Some function.

    Raises
    ------
    ValueError
        Something went wrong.

    Warns
    -----
    RuntimeWarning
        Something will go wrong.
    """
    warnings.warn("Something", RuntimeWarning)
    raise ValueError("Another")

when run with pydoclint says:

    3: DOC503: Function `foo` exceptions in the "Raises" section in the docstring do not match those in the function body. Raised exceptions in the docstring: ['RuntimeWarning', 'ValueError']. Raised exceptions in the body: ['ValueError'].

Really the function raises only one exception, and warns about another.

[jsh9]

Thanks!

I think the culprit is the underlying docstring parser, which currently only recognizes these sections.

I also own this docstring parser, so I'll need to fix that first.