title: Docstrings - one line vs multiple line
body: <p>I'm adding some (<a href="http://epydoc.sourceforge.net/manual-fields.html">epydoc</a>) documentation to a package I've written, and I'm coming across a lot of instances where I'm repeating myself a multitude of times. </p>
  
  <pre><code>def script_running(self, script):
      """Return if script is running
  
      @param script: Script to check whether running
  
      @return: B{True} if script is running, B{False} otherwise
      @rtype: C{bool}
      """
  </code></pre>
  
  <p><a href="http://www.python.org/dev/peps/pep-0257/#one-line-docstrings">PEP257</a> says that:</p>
  
  <blockquote>
    <p>One-liners are for really obvious cases. </p>
  </blockquote>
  
  <p>and also </p>
  
  <blockquote>
    <p>The docstring for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable).</p>
  </blockquote>
  
  <hr>
  
  <p>Is there a general guideline or standard practice for when to draw the line between a one-liner (description) and full param/return fields? </p>
  
  <p>Or when generating documentation should I include every applicable field for each function, regardless of how repetitive it seems?</p>
  
  <p>Bonus question: Syntactically, what's the best way to describe the <code>script</code> param? </p>