Allow one way (allow raises docs even if they don't exist in the body) skip for checking raises

[armanckeser]

Currently the option -scr works as follows:

7. --skip-checking-raises (shortform: -scr, default: False)
   If True, pydoclint won’t report DOC501 or DOC502 if there are raise statements in the function/method but there aren’t any “raises” sections in the docstring (or vice versa).

The vice versa part means that

def my_func():
	"""Simple func

	Raises:
		Exception: underlying function might raise
	"""
	might_raise_exception()

the above will fail pydoclint with skip-checking-raises=false.

I understand that pydoclint doesn't want to add dynamic or dynamic-ish checks to keep performance, so its unlikely for a feature like "capture all possible exceptions from the source code up and force documentation" to exist, however with the all or nothing approach, -scr option somewhat disincentivizes documenting pass-through exceptions as it would require wrapping logic in try-except-raise.

It would be nice to allow a one way option, where pydoclint forces you to document exceptions you raise in the body, but also allows you to mention any other exception.

[jsh9]

Hi, I like this idea in principle.

A side effect that I wouldn't want to see (if I implement what you suggest above) is:

• In a function, I have 3 different exceptions and the docstring documents these 3. No pass-through exceptions from any subroutines.
• Some day, I modify this function to remove 2 of the exceptions but I forget to delete the 2 exceptions in the docstring
• If I have this proposed flag on (for pass-through exceptions in other functions), pydoclint would miss this function

I think a compromise would be necessary. I'm thinking that users would need to signal, in the docstring, that a particular exception is a pass-through exception. Any suggestions on how to signal this?

[armanckeser]

How about a Propagates section?

def my_func():
    """Simple func

    Raises:
        ValueError: this function explicitly raises this

    Propagates:
        IOError: underlying file operation might fail
    """
    ...

Its quite clear, would be backwards compatible if you implement it as an opt in feature since it doesn't exist in the original doc styles. The name is self explanatory and likely better than using a tag per exception as the grouping will likely be more clear. There might need to be some deduping between raises and propagates errors but that seems acceptable.