title: Should I list class methods in the class docstring?
body: <p>I am a bit confused by the PEP257 standard for documenting classes.</p>
  
  <p>It says, "The docstring for a class should summarize its behavior and list the public methods and instance variables"</p>
  
  <p>But it also says that all functions should have dosctrings (which, of course, I want, so that help() works).</p>
  
  <p>But this seems to involve duplication i.e.</p>
  
  <pre><code>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...
  </code></pre>
  
  <p>This then is rather error prone because it means that when I realise that <code>__init__</code> 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.</p>
  
  <p>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.</p>
  
  <p>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?</p>
  
  <p>TIA</p>