check-docstring-first false positive on attribute docstrings #159
Description
Attribute docstrings, as defined in PEP-257 are strings immediately following top level module names. For example:
name = "my variable" """the name used by the module for x, y, and z"""
The check-docstring-first incorrectly identifies this attribute docstring as a module docstring, indicating either Multiple module docstrings (first docstring on line N). or Module docstring appears after code (code seen on line N)..
In light of this issue, I'm not sure the check-docstring-first check has much value at all. At the very least, the check should not be failing when a docstring follows an assignment.
Activity
asottile commented on Dec 24, 2016
The goal of the hook was mostly to prevent imports-then-docstring (an especially common/easy mistake with future imports and docstrings), perhaps it can be adjusted to stop searching after it finds some non-import code (similar to the algorithm used in https://github.com/asottile/reorder_python_imports)
Disable check-docstring-first check
sdouche commented on Jul 10, 2019
Hey @asottile :)
Do you think is possible to resolve this issue?
asottile commented on Jul 10, 2019
Doubt it, unless you can come up with a good heuristic for differentiating the mistake and the intentional "attribute docstring"
sdouche commented on Jul 12, 2019
@asottile Understood. Maybe close this issue then?
asottile commented on Jul 12, 2019
It may be possible, I haven't invested any time into this particular issue as I don't use "attribute docstrings" - - normal comments work fine for me
lukelbd commented on Nov 29, 2019
@asottile People use "attribute docstrings" becuase the sphinx autosummary documentation generator looks for docstrings following class-level and module-level variables and uses them to generate website documentation. This would actually be a useful feature for a lot of people.
asottile commented on Nov 29, 2019
This issue is still open, if you can come up with a heuristic that properly identifies "attribute docstrings" vs the mistakes it currently catches then I'd happily entertain a tested patch. You'll notice I marked this as a bug and I haven't closed it, so please be careful of asserting that I'm being dismissive. I simply don't have any reason to work on this myself since I don't use that feature, but I'd be happy to guide you through implementing this :)
I'm pretty sure you can also use this as a workaround (or at least I've seen comments like this in the past):
(I might be misremembering the exact format, it's been a while!)
lukelbd commented on Nov 29, 2019
Sorry didn't mean to be rude; I corrected my tone! Obviously I'm super grateful for this project. I didn't know about #: -- maybe that ought to close this issue actually.
ryanrhee commented on Jan 18, 2022
I just ran into this. FWIW, #: is not a part of PEP-257, and (more importantly for me,) comments starting with #: are not picked up by vscode the way that attribute docstrings are.
just fyi, that there are use cases for which the #: workaround doesn't work.
ci: remove docstring first check from pre-commit
Drop check-docstring-first due to pre-commit/pre-commit-hooks#159
Drop check-docstring-first due to pre-commit/pre-commit-hooks#159
chore(pre-commit): remove check-docstring-first
chore(pre-commit): remove check-docstring-first
chore(pre-commit): remove check-docstring-first
chore(pre-commit): remove check-docstring-first
SirTakobi commented on Jan 5, 2023