Docstrings - one line vs multiple line

Question

I'm adding some (epydoc) 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.

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}
    """

PEP257 says that:

One-liners are for really obvious cases.

and also

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).

---

Is there a general guideline or standard practice for when to draw the line between a one-liner (description) and full param/return fields?

Or when generating documentation should I include every applicable field for each function, regardless of how repetitive it seems?

Bonus question: Syntactically, what's the best way to describe the script param?

Answer 1

The general guideline you are looking for is right in PEP257 in what you quoted, maybe you just need to see it in action.

Your function is a good candidate for a one-line docstring ("really obvious cases"):

def script_running(self, script):
    """Check if the script is running."""

Usually if you say that a function is checking something it means that it's going to return True or False, but if you like you could be more specific:

def script_running(self, script):
    """Return True if the script is running, False otherwise."""

Once again all in one line.

I would probably also change the name of your function, because there's no need to emphasize on what the function works in its name (a script). A function name should be something sweet, short and meaningful about what the function does. Probably I'd go with:

def check_running(self, script):
    """Return True if the script is running, False otherwise."""

Sometimes the function-name-imagination is tired by all the coding, but you should try anyway to do your best.

For a multiline example, let me borrow a docstring from the google guidelines:

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
    """Fetches rows from a Bigtable.

    Retrieves rows pertaining to the given keys from the Table instance
    represented by big_table.  Silly things may happen if
    other_silly_variable is not None.

    Args:
        big_table: An open Bigtable Table instance.
        keys: A sequence of strings representing the key of each table row
            to fetch.
        other_silly_variable: Another optional variable, that has a much
            longer name than the other args, and which does nothing.

    Returns:
        A dict mapping keys to the corresponding table row data
        fetched. Each row is represented as a tuple of strings. For
        example:

        {'Serak': ('Rigel VII', 'Preparer'),
         'Zim': ('Irk', 'Invader'),
         'Lrrr': ('Omicron Persei 8', 'Emperor')}

        If a key from the keys argument is missing from the dictionary,
        then that row was not found in the table.

    Raises:
        IOError: An error occurred accessing the bigtable.Table object.
    """

This could be one way to "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)".

You might also be interested to look at this example of pypi project that it's meant to be documented with Sphinx.

My 2 cents: Guidelines are meant to give you an idea about what you should and shouldn't do, but they are not strict rules that you have to blindly follow. So at the end choose what you feel to be better.

---

I would like to clear something that is been said in another answer about hitting the Maximum Line Length with a docstring.

PEP8 tells you to "Limit all lines to a maximum of 79 characters" even though at the end everyone does 80.

This are 80 characters:

--------------------------------------------------------------------------------

And this may be an edge case where a little long one sentence is all you really need:

def my_long_doc_function(arg1, arg2):
    """This docstring is long, it's a little looonger than the 80 characters
    limit.
    
    """

Is like a one-line docstring, meaning that is for really obvious cases, but on your editor (with the 80 character limit) is on multiple lines.