src/twisted/mail/test/pop3testserver.py:31: Module docstring appears after code (code seen on line 8).
docs/conch/examples/sshsimpleclient.py:14: Module docstring appears after code (code seen on line 5).
src/twisted/test/test_formmethod.py:5: Module docstring appears after code (code seen on line 3).
src/twisted/conch/ssh/forwarding.py:252: Multiple module docstrings (first docstring on line 4).
docs/conch/examples/sshsimpleserver.py:21: Module docstring appears after code (code seen on line 6).
src/twisted/web/http.py:1903: Multiple module docstrings (first docstring on line 5).
src/twisted/web/_flatten.py:41: Multiple module docstrings (first docstring on line 5).
Most of these are real. (Thank you!) However, the last two are incorrectly flagging docstrings applied to module-level variables. For example:
Could the hook be refined to not flag docstrings that follow definitions? Alternatively, could there be a flag to disable the "multiple docstrings" part?
asottile
commented
1 month ago
In https://github.com/twisted/twisted/pull/12261 I introduced the check-docstring-first hook to the Twisted repository. There were some failures:
Most of these are real. (Thank you!) However, the last two are incorrectly flagging docstrings applied to module-level variables. For example:
https://github.com/twisted/twisted/blob/f6d54d6b0a5560d6de8297dd02d8ba415e499461/src/twisted/web/http.py#L1890-L1928
This is a docstring intended for Pydoctor, a documentation tool. You can see it rendered here. Note that Sphinx autodoc also handles docstrings that follow definitions.
Could the hook be refined to not flag docstrings that follow definitions? Alternatively, could there be a flag to disable the "multiple docstrings" part?