There is an official answer, in PEP 257 (the docstring PEP), which is arguably authoritative:
The class constructor should be documented in the docstring for its
__init__
method.
This is quite logical, as this is the usual procedure for functions and methods, and __init__()
is not an exception.
As a consequence, this puts the code and its documentation in the same place, which helps maintenance.
Finally, tools that display documentation to the user (like Jupyter, or the built-in Python shell command help()
) are more likely to correctly display the documentation of your code. In practice, they do display the __init__()
docstring automatically when you ask for help on the class, so this is one more reason to follow the official convention of putting the initialization documentation in __init__()
.