DocStrings giving a `pointless-string-statement`

[mrpbennett]

Current problem

I have some docstrings to explain what certain bits of code does something like

"""
Endpoints for populating the UI with data. These need to consist of some joins.
"""

pylint gives me the following warning:

String statement has no effectpylint(pointless-string-statement)

Desired solution

Although there is no point to this docstring apart from comments. Would it be possible to have a different type of warning message?

Or should I be putting these type of comments in a # and not a docstring? What If I wanted a multi line comment?

Additional context

No response

[DanielNoord]

Yeah, it is indeed preferred to do this with comments. For multi-line comments you can just use a # at the start of every line.

They only "allowed" pointless statement is at the top of a module as this function as the module docstring.

[KotlinIsland]

@DanielNoord PyCharm, VSCode and pdoc3 all work with this syntax, and do not work with the comment approach your have suggested. I think it would be expected for pylint to cooperate with this use case.

For context: I have disabled this rule for this reason alone, yet I would still very much like useless strings to be reported against. I recently ran into a dead doc-string that was accidentally not removed during a refactor.

[Pierre-Sassoulas]

Could you give examples of code you expect to not raise @KotlinIsland ?

[KotlinIsland]

All of the examples here: https://github.com/PyCQA/pydocstyle/issues/630#issue-1586943597

Additionally I would expect:

a = 1
"""This is used as a doc string and shouldn't be reported as unused"""

a = 2
"""This is not the initial declaration of `a`, is not a doc string, and is actually an unused string. This should be an error"""

[DanielNoord]

This behaviour is part of a PEP that has been rejected about 15 years ago.

Although I agree it is nice, I'm not sure pylint should change behaviour here,

[DetachHead]

i don't see why pylint can't support it just because the PEP was rejected, especially since both pycharm and vscode support it

[Pierre-Sassoulas]

If this became the standard despite being rejected in a PEP then it will feel like a problem with pylint in the long run. On the other hand I don't think variable have a __doc__ attribute the way module do, so the "docstring" would effectively be useless as far as the python interpreter is concerned.

I think the fact that it make pylint really annoying when using pycharm/vscode warrant to at least be able to do it optionally.

[DanielNoord]

Fair enough! Let's do this!