Rules to enforce either doc comments or docstrings for variables/attributes

[sh-at-cs]

Summary

Background

There are two distinct conventions in Python for attaching documentation to module-level variables and class attributes:

1. A docstring directly below, e.g.:

   name: str
   """
   The user's full name.
   
   Should not include middle names.
   """

2. A #:¹ doc comment directly above, e.g.:

   #: The user's full name
   #:
   #: Should not include middle names.
   name: str

I believe the docstring-below approach (1) is more common nowadays.

The doc-comment-above approach (2) was (according to an LLM's recollections) originally introduced by epydoc and then adopted by Sphinx.

Rule suggestion

It would be nice if there were rules to enforce either one of these approaches, complaining if the other one is used for a variable/attribute.

If you don't want to implement a rule to enforce doc comments because they seem kind of outdated anyway, it would also be fine to only have a rule that enforces docstrings and complains about doc comments.

Footnotes

1. Spelled out so people may find this issue more easily: hash colon ↩