[Django] #19907: Better docstrings with parameter and return information
Django
-------------------------------+----------------------
Reporter: tga | Owner: nobody
Type: Uncategorized | Status: new
Component: Uncategorized | Version: master
Severity: Normal | Keywords: comments
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------+----------------------
Many functions need better parameter documentation in their docstring
because without it, it is difficult to understand what's going on.
Bonus points while doing this: use Sphinx style (:param foo: Description).
1) it provides a standard way of writing docstrings,
2) is already in use in docs, and
3) it will also help with IDE support.
--
Ticket URL: <https://code.djangoproject.com/ticket/19907>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: tga | Owner: nobody
Type: Uncategorized | Status: closed
Component: Uncategorized | Version: master
Severity: Normal | Resolution: invalid
Keywords: comments | Triage Stage: Unreviewed
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by tga):
* status: new => closed
* needs_better_patch: => 0
* resolution: => invalid
* needs_tests: => 0
* needs_docs: => 0
--
Ticket URL: <https://code.djangoproject.com/ticket/19907#comment:1>
Django
--------------------------------------+------------------------------------
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
Easy pickings: 0 | UI/UX: 0
Changes (by ptone):
* status: closed => new
* type: Uncategorized => Cleanup/optimization
* component: Uncategorized => Documentation
* resolution: invalid =>
* stage: Unreviewed => Accepted
Old description:
> Many functions need better parameter documentation in their docstring
> because without it, it is difficult to understand what's going on.
>
> Bonus points while doing this: use Sphinx style (:param foo:
> Description).
>
> 1) it provides a standard way of writing docstrings,
>
> 2) is already in use in docs, and
>
> 3) it will also help with IDE support.
New description:
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.
--
Comment:
I'm modifying the description and reopening this to target the improvement
as something for the style guide
--
Ticket URL: <https://code.djangoproject.com/ticket/19907#comment:2>
Django
--------------------------------------+------------------------------------
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: comments | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 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
--------------------------------------+------------------------------------
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: comments | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by timo):
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/19907#comment:4>
Django
--------------------------------------+------------------------------------
Type: Cleanup/optimization | Status: closed
Component: Documentation | Version: master
Severity: Normal | Resolution: wontfix
Keywords: comments | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Changes (by aaugustin):
* status: new => closed
* resolution: => wontfix
Comment:
I agree with Tim.
--
Ticket URL: <https://code.djangoproject.com/ticket/19907#comment:5>