Put docstrings on special methods?
I'm trying to decide what information to put in the class docstring and what t开发者_如何学运维o put in the __init__
method docstring. Up until now I've been putting an overview of the class and how to work with it in the class docstring, while stuff directly related to initialization (argument details etc.) I put in the __init__
docstring.
Today I started wondering if this was the right way of doing it, so I looked at a couple of built-in modules, and I see that the __init__
method almost never has a docstring. According to PEP8, "Docstrings are not necessary for non-public methods", but isn't __init__
public?
In the same vein, what about other special methods, like __getitem__
, __getattr__
or __new__
, should they have docstrings? Or should I just mention the consequences they have in the class docstring?
Straight from PEP 257:
Public methods (including the
__init__
constructor) should also have docstrings.
[...]
The class constructor should be documented in the docstring for its
__init__
method.
精彩评论