False positive DOC201

[ddelange]

Hi 👋

This function edits inplace and doesn't have a return value:

def smoothen_values(list_smooth: list[str], key: str):
    """Edit list_smooth inplace.

    Args:
        list_smooth: A list with keys.
        key: The key to add.
    """
    if len(list_smooth) <= 1:
        return
    list_smooth += [key]

It throws a DOC201: Function smoothen_values does not have a return section in docstring false positive.

[jsh9]

Interesting. This is an edge case that this option does not cover: https://jsh9.github.io/pydoclint/config_options.html#9---require-return-section-when-returning-nothing-shortform--rrs-default-false

I think I'll add a patch to cover this case.

[jsh9]

Hi @ddelange , upon double checking, I found that this is by design rather than a bug.

I actually even have a test case to cover this:

pydoclint/tests/data/google/no_return_section/cases.py

Lines 42 to 49 in 22b9b37

	def func5(text: str):
	"""A return section is always required because it has explicit "return"
	in the function body (even if it is just "return")
	Args:
	text (str): Text for the function
	"""
	return

[ddelange]

OK, let's leave it at that then 👍

[krispycheez]

I see that this is already closed, but was wondering if you could go into more detail about the rationale behind handling this edge case in this way. The way I am interpreting it, you are assuming that the function writer specifically chose to use "return" when it was not required. Therefore, they should have to add a section to the docstring because this is not a normal "return nothing" function. But in more complex functions, "return" might be used to escape a deeply nested set of conditionals, and is arguably required (at least without having to restructure the logic of the function). I would personally consider such a function a normal "return nothing" function that should not require a Returns section in the docstring.

My two cents is a "Returns" docstring section should only be required if there is an empty "return" statement in the function that is not conditional (i.e. the last line of the function is "return"). The test you posted would still work as desired in that case and require a "Returns" section in the docstring, but the original example posted would not require it.