在特殊方法上添加文档字符串吗？

Question

我在考虑应该在类的文档字符串里放什么信息，以及在__init__方法的文档字符串里放什么。到目前为止，我一直把类的概述和使用方法放在类的文档字符串里，而跟初始化直接相关的内容（比如参数的细节等）则放在__init__的文档字符串里。

今天我开始怀疑这样做是否正确，于是我查看了一些内置模块，发现__init__方法几乎从来没有文档字符串。根据PEP8的规定，“非公共方法不需要文档字符串”，但__init__难道不是公共的吗？

同样的，其他特殊方法，比如__getitem__、__getattr__或__new__，它们也应该有文档字符串吗？还是说我只需要在类的文档字符串里提到它们的影响就可以了？

Answer 1

直接来自 PEP 257 的内容：

公共方法（包括 __init__ 这个构造函数）也应该有文档字符串。

[...]

类的构造函数应该在它的 __init__ 方法的文档字符串中进行说明。