I am a bit confused by the PEP257 standard for documenting classes.
It says, "The docstring for a class should summarize its behavior and list the public methods and instance variables"
But it also says that all functions should have dosctrings (which, of course, I want, so that help() works).
But this seems to involve duplication i.e.
class foo:
"""A class
Attributes
----------
bar : str
A string
Methods
-------
__init__(fish):
Constructor, fish is a str which self.bar will be set to.
baz():
A function which does blah
"""
def __init__(self, fish):
"""
Constructs an XRTProductRequest object.
Parameters
----------
fish : str
A string, which the self.bar attribute will be set to.
"""
etc...
This then is rather error prone because it means that when I realise that __init__ also needs to recieve an int, then I have to remember to update the docs in 2 places, which I can guarantee I will forget.
It also makes the pydoc output duplicated: it prints my class docstring, but then says, "Methods defined here" and goes on to list all of the methods, via their own docstrings.
So, is this duplication really part of PEP257, or am I mis-reading it? Should I drop the "Methods"section of the class docstring, since each method has its own docstring? Or is this duplication really part of the standard?
TIA
Yes just drop the methods section from the class docstring. I've never ever seen something like that used.(It is used in few places in the standard library.) The class docstring needs to just describe the class and the docstring of individual methods then handle describing themselves.
Also the wording in the PEP to me means that the class docstring "should" list the public methods, but not describe them in any other way.(This is also how the above standard library example does it.) But as said, I would never even do that, since the code speaks for itself and that kind of listing is bound to get out-of-date.
Final note: I personally prefer to use the Google docstring style, because to me it's the clearest and cleanest.