#19907: Add additional style guidance for docstrings
--------------------------------------+------------------------------------
Reporter: tga | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: comments | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------
Comment (by 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/19907#comment:3>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
For more options, visit https://groups.google.com/groups/opt_out.
