Add additional style guidance for docstrings

[tga]

Many functions need better parameter documentation in their docstring because without it, it is difficult to understand what's going on.

​https://docs.djangoproject.com/en/1.4/internals/contributing/writing-code/coding-style/ contains some basic guidance on docstrings, but nothing about if, when, or how arguments and return values are documented.

Google provides one such style guide which has been popularly adopted:

​http://google-styleguide.googlecode.com/svn/trunk/pyguide.html#Comments

Benefits include:

• it provides a standard way of writing docstrings,
• it will also help with IDE and interactive shell support.
• Helps people reading the source code.

[Preston Holmes]

I'm modifying the description and reopening this to target the improvement as something for the style guide

[tga]

Ad-hoc (current)

def sql_destroy_indexes_for_fields(self, model, fields, style):
    """
    Generates a SQL statement list with the DROP INDEX SQL statements for multiple model fields.

    `Style` object as returned by either color_style() or no_style() in django.core.management.color
    """

Sphinx Style

def sql_destroy_indexes_for_fields(self, model, fields, style):
    """
    Generates the DROP INDEX SQL statements for multiple model fields.

    :param fields: Fields to generate SQL for
    :param style: `Style` object as returned by either color_style() or no_style() in django.core.management.color
    :returns: [SQL statement list]
    """

Google Style

def sql_destroy_indexes_for_fields(self, model, fields, style):
    """
    Generates the DROP INDEX SQL statements for multiple model fields.

    Args:
        fields: Fields to generate SQL for
        style: `Style` object as returned by either color_style() or no_style() in django.core.management.color
        
    Returns:
        [SQL statement list]
    """

Suggestion: to avoid fluff, parameters should only be included in the docstring if they are actually documented.

[Tim Graham]

I am in favor of continuing to use the current ad-hoc style. I find the other styles very verbose and distracting. Hopefully most code is simple enough that it doesn't need verbose docstrings.

[Aymeric Augustin]

I agree with Tim.