Update of /cvsroot/docstring/dps/spec
In directory usw-pr-cvs1:/tmp/cvs-serv19455/dps/spec
Modified Files:
pep-0257.txt
Log Message:
added "methods" to descriptions, Unicode strings
Index: pep-0257.txt
===================================================================
RCS file: /cvsroot/docstring/dps/spec/pep-0257.txt,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -d -r1.1.1.1 -r1.2
*** pep-0257.txt 2001/07/22 22:36:21 1.1.1.1
--- pep-0257.txt 2001/08/04 15:45:43 1.2
***************
*** 71,75 ****
For consistency, always use """triple double quotes""" around
docstrings. Use r"""raw triple double quotes""" if you use any
! backslashes in your docstrings.
There are two forms of docstrings: one-liners and multi-line
--- 71,76 ----
For consistency, always use """triple double quotes""" around
docstrings. Use r"""raw triple double quotes""" if you use any
! backslashes in your docstrings. For Unicode docstrings, use
! u"""Unicode triple-quoted strings""".
There are two forms of docstrings: one-liners and multi-line
***************
*** 99,107 ****
- The docstring is a phrase ending in a period. It prescribes the
! function's effect as a command ("Do this", "Return that"), not
! as a description: e.g. don't write "Returns the pathname ..."
- The one-line docstring should NOT be a "signature" reiterating
! the function parameters (which can be obtained by
introspection). Don't do::
--- 100,109 ----
- The docstring is a phrase ending in a period. It prescribes the
! function or method's effect as a command ("Do this", "Return
! that"), not as a description: e.g. don't write "Returns the
! pathname ..."
- The one-line docstring should NOT be a "signature" reiterating
! the function/method parameters (which can be obtained by
introspection). Don't do::
***************
*** 133,141 ****
line, and the docstring needs to be offset from the first method
by a blank line; for symmetry, put a blank line between the class
! header and the docstring. Docstrings documenting functions
! generally don't have this requirement, unless the function's body
! is written as a number of blank-line separated sections -- in this
! case, treat the docstring as another section, and precede it with
! a blank line.
The docstring of a script (a stand-alone program) should be usable
--- 135,143 ----
line, and the docstring needs to be offset from the first method
by a blank line; for symmetry, put a blank line between the class
! header and the docstring. Docstrings documenting functions or
! methods generally don't have this requirement, unless the function
! or method's body is written as a number of blank-line separated
! sections -- in this case, treat the docstring as another section,
! and precede it with a blank line.
The docstring of a script (a stand-alone program) should be usable
|
