missing-docstring for constants and types

[JosuaKrause]

Current problem

currently there is no way to enforce adding docstrings to constants or types. Since 3.9 it is possible to properly annotate constants or types via:

from __future__ import annotations
from typing import Annotated, TypeAlias

Seconds: TypeAlias = Annotated[float, "seconds"]
DAY: Annotated[Seconds, "number of seconds in a day"] = 86400

but even before that

from typing import TypeAlias

Seconds: TypeAlias = float
"""seconds"""

DAY: Seconds = 86400
"""number of seconds in a day"""

is correctly interpreted as docstrings by IDEs and shows up in the tooltips when hovering the symbol.

it would be great to be able to enforce docstrings for those symbols as it is otherwise easy to miss annotating them

Desired solution

the missing-docstring check could be expanded to include those or a new check missing-constant-docstring (or something similar) could be added

Additional context

here is a SO answer talking about the proper way to annotate constants: https://stackoverflow.com/questions/8820276/docstring-for-variable

[DanielNoord]

Note that this way of doing docstrings is not officially supported as the original PEP that introduced it was rejected. I'm not sure we should recommend something that is not actually part of the Python spec.

[JosuaKrause]

Well it's the only way to do it at this time and IDEs support it