id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
19907	Add additional style guidance for docstrings	tga	nobody	"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."	Cleanup/optimization	new	Documentation	dev	Normal		comments		Accepted	0	0	0	0	0	0