False positive DOC503 in 0.5.12

[Waschenbacher]

False positive DOC503 error in version 0.5.12?

------------------------Bug report---------------------
[Example]:

def check_nonnegative_bug(number: float) -> None:
    """Check if the provided number is non-negative.

    Args:
        number(float): The number to check.

    Returns:
        None

    Raises:
        ValueError: when the number is less than zero.
        ValueError: when the number is zero.
    """
    if number < 0.0:
        raise ValueError("The number must be positive.")
    if number == 0.0:
        raise ValueError("The number must be positive.")

[To reproduce]
Running pydoclint --style=google --check-return-types=False . on terminal in a conda env (Env details see below) gives the pydoclint error message below.

[pydoclint error message]

DOC503: Function check_positive exceptions in the "Raises" section in the docstring do not match those in the function body Raises values in the docstring: ['ValueError', 'ValueError']. Raised exceptions in the body: ['ValueError'].

[Expected output]

• no violations

[Environment]

• pydoclint 0.5.12 pypi_0 pypi
• python 3.10.16 h870587a_1_cpython conda-forge

------------------------Good example---------------------
My guess: It seems that the false alarm on DOC503 occurs only when there are multiple errors of the same type. For errors of different types (see the example below), no pydoclint complaints.

[Example]:

def check_nonnegative_ok(number: float) -> None:
    """Check if the provided number is non-negative.

    Args:
        number(float): The number to check.

    Returns:
        None

    Raises:
        TypeError: when the type of number is not float.
        ValueError: when the number is less than zero.
    """
    if not isinstance(number, float):
        raise TypeError("The type of number must be float.")
    if number <= 0.0:
        raise ValueError("The number must be non-negative.")

[Output]:

• no violations

[Other details]:
All other details are the same as in the bug-example.

[jsh9]

Hi @Waschenbacher , this is not a bug, but a feature.

Please see the code here:

pydoclint/pydoclint/utils/return_yield_raise.py

Lines 98 to 100 in dfd9494

	def getRaisedExceptions(node: FuncOrAsyncFuncDef) -> list[str]:
	"""Get the raised exceptions in a function node as a sorted list"""
	return sorted(set(_getRaisedExceptions(node)))

We deduplicated and sorted the exceptions within a function. The reason is that very often we have functions with many exceptions (e.g., 5 TypeErrors, 3 ValueErrors, 2 IOErrors, ...), so it's not very practical to list every raised exception in the correct order in the docstring. (Note: if you don't want deduplication, the only sensible for a linter is to enforce the order.)

It's not difficult to add another config option to suppress deduplication, but the key question is whether we should add such an option. My current position is no, unless there are very compelling reasons.