Niko FöhrHelp me interpret PEP-257 which says "The class constructor should be documented in the docstring for its __init__ method. "
Does this mean that the constructor parameters should be documented in the class docstring or just the opposite?
JoeP@fohrloop
My interpretation is that no, that's talking about the __init__ method docstring. The class docstring is distinct, and:
"The docstring for a class should summarize its behavior and list the public methods and instance variables."
My interpretation is that no, that's talking about the __init__ method docstring. The class docstring is distinct, and:
"The docstring for a class should summarize its behavior and list the public methods and instance variables."
@JoeP Thank you for the response. I wish there were one example in the PEP-257 which would make it clear :)
frague59 ⏚@fohrloop Hi - As quoted from the top of the PEP-257,
"All modules should normally have docstrings, and all functions and classes exported by a module should also have docstrings. Public methods (including the __init__ constructor) should also have docstrings."
For me, you should document the parameters of the constructor in the __init__(self, ...) body.
That's what I can see used in most python packages I see...
@frague59 That's true it says on the top that the __init__ constructor should have a docstring. The reason why I'm interested is that Numpy Doc style, which I've been "implementing" for years, to my surprise puts the Parameters in the class docstring.
@frague59 And when I was documenting the constructor parameters in the __init__ method, the docs Sphinx creates (1) look repetitive (2) Have parameter explanations quite far away from the class definition:
@frague59 When Parameters is put to the class docstring, the docs Sphinx creates have (1) Constructor signature shown just once and (2) Parameter docs closer to the constructor:
