parameter_documentation: Add magic phrase to ignore missing return documentation

[Daisy-Volant]

Current problem

I have an API wrapper function which I would like to link to the API's documentation for params and return, but there is only a way to do this with parameters currently with the "For the parameters, see" escape hatch.

Desired solution

I would like an extra escape hatch for return documentation, that preferably works together with the existing param comment, eg:

• "For the return, see"
• "For the parameters and return, see"

This escape hatch would avoid linting when there is missing :return: section, or in the combined form both.

Additional context

I googled around and checked the sources and couldn't find this implemented already, but if it is and I've just missed it feel free to close.

[Pierre-Sassoulas]

Thank you for opening the issue. From an implementation standpoint, this is modifying this:

pylint/pylint/extensions/_check_docs_utils.py

Lines 283 to 288 in 8f11288

	re_for_parameters_see = re.compile(
	r"""
	For\s+the\s+(other)?\s*parameters\s*,\s+see
	""",
	re.X | re.S,
	)

And this:

pylint/pylint/extensions/docparams.py

Lines 524 to 526 in 8f11288

	* If the text "For the parameters, see" or "For the other parameters,
	see" (ignoring additional white-space) is mentioned in the docstring,
	missing parameter documentation is tolerated.

Need some discussion about what we want exactly before rushing to implementation, because it's starting to look like there's multiple way to do it.