Opened 12 years ago

Last modified 10 years ago

#19907 closed Cleanup/optimization

Add additional style guidance for docstrings — at Version 2

Reported by: tga Owned by: nobody
Component: Documentation Version: dev
Severity: Normal Keywords: comments
Cc: Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description (last modified by Preston Holmes)

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.

Change History (2)

comment:1 by tga, 12 years ago

Resolution: invalid
Status: newclosed

comment:2 by Preston Holmes, 12 years ago

Component: UncategorizedDocumentation
Description: modified (diff)
Resolution: invalid
Status: closednew
Summary: Better docstrings with parameter and return informationAdd additional style guidance for docstrings
Triage Stage: UnreviewedAccepted
Type: UncategorizedCleanup/optimization

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

Note: See TracTickets for help on using tickets.
Back to Top