Changes between Initial Version and Version 2 of Ticket #19907


Ignore:
Timestamp:
Feb 24, 2013, 12:43:51 PM (11 years ago)
Author:
Preston Holmes
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 Component Uncategorized → Documentation
    • Property Triage Stage Unreviewed → Accepted
    • Property Summary Better docstrings with parameter and return information → Add additional style guidance for docstrings
    • Property Type Uncategorized → Cleanup/optimization

  • 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