#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
--------------------------------------+------------------------------------
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 <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.
