Allow short docstrings in pydoclint

[valentincalomme]

As of ruff==0.6.2, pydoclint rules (DOC) doesn't allow any settings. If prioritization is required, I would personally really value having the --skip-checking-short-docstrings setting (see: https://jsh9.github.io/pydoclint/config_options.html)

This is currently blocking me from using the rule altogether.

[tjkuson]

Possibly related to #5860

EDIT: I should probably elaborate. The proposal to restrict docstring diagnostics based on docstring complexity (what you describe) is distinct to what I linked (which is a proposal to limited based on function complexity). However, they face overlapping design challenges, so it might make sense to link them.

[AlexWaygood]

@valentincalomme or @augustelalande, would you be able to elaborate a bit more about why this config option is desirable? I don't feel like #13302 gives a great description of what the config option is for right now, but I'm not sure how to improve it as I don't fully feel like I understand why it would be useful.

[valentincalomme]

@AlexWaygood for me it is desirable in the very simple scenario where I want to add a "one-liner" docstring, just to explain briefly what my method does. I dont' want pydoclint to complain that I am missing descriptions for the parameters. Actually, a good description is how darglint describes their strictness (https://pypi.org/project/darglint/). They have 3 modes:

• short: One-line descriptions are acceptable; anything more and the docstring will be fully checked.
• long: One-line descriptions and descriptions without arguments/returns/yields/etc. sections will be allowed. Anything more, and the docstring will be fully checked.
• full: (Default) Docstrings will be fully checked.

Right now, the DOC rules are always set to "full" strictness, which forces all docstrings to include everything (parameters, returns, raises, etc.). I personally like to follow the "if you add it, it needs to be correct, but omitting it is ok" approach for docstrings

[tmke8]

I, too, always use --skip-checking-short-docstrings for pylint. I'm using type hints for all parameters anyway, so if it's just a simple function, I don't feel the need to document all parameters explicitly with a sentence; all I want is a one-line explanation of what the function does:

def square(x: float) -> float:
    """Square the given number."""
    ...

I mean I guess it is a little weird to tie the requirement to document all parameters to the number of lines in the docstring, but I found this heuristic to work well.

[tmke8]

Maybe a better rule would actually be:

• If one :param ...: has been specified, all params and return value and exceptions need to be documented.

Instead of

• If the docstring has more than one line, all params and return value and exceptions need to be documented.