Changes between Initial Version and Version 2 of Ticket #19907


Ignore:
Timestamp:
02/24/2013 12:43:51 PM (2 years ago)
Author:
ptone
Comment:

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

Legend:

Unmodified
Added
Removed
Modified
  • Ticket #19907

    • Property Patch needs improvement unset
    • Property Component changed from Uncategorized to Documentation
    • Property Needs tests unset
    • Property Summary changed from Better docstrings with parameter and return information to Add additional style guidance for docstrings
    • Property Type changed from Uncategorized to Cleanup/optimization
    • Property Needs documentation unset
    • Property Triage Stage changed from Unreviewed to Accepted
  • Ticket #19907 – Description

    initial v2  
    11Many functions need better parameter documentation in their docstring because without it, it is difficult to understand what's going on.
    22
    3 Bonus points while doing this: use Sphinx style (:param foo: Description).
     3https://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.
     4
     5Google provides one such style guide which has been popularly adopted:
     6
     7http://google-styleguide.googlecode.com/svn/trunk/pyguide.html#Comments
    48 
    5 1) it provides a standard way of writing docstrings,
     9Benefits include:
    610
    7 2) is already in use in docs, and
    8 
    9 3) it will also help with IDE support.
     11* it provides a standard way of writing docstrings,
     12* it will also help with IDE and interactive shell support.
     13* Helps people reading the source code.
Back to Top