Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

#926501: add info where to put the docstring.

This commit is contained in:
Georg Brandl 2008-07-20 11:50:29 +00:00
parent 61d5c43011
commit e64f738507
2 changed files with 22 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
Doc/glossary.rst
View File

@ -123,6 +123,14 @@ Glossary
of :class:`dict` much resembles that for :class:`list`, but the keys can
be any object with a :meth:`__hash__` function, not just integers starting
from zero. Called a hash in Perl.
docstring
A docstring ("documentation string") is a string literal that appears as
the first thing in a class or function suite. While ignored when the
suite is executed, it is recognized by the compiler and put into the
:attr:`__doc__` attribute of the class or function. Since it is available
via introspection, it is the canonical place for documentation of the
object.
duck-typing
Pythonic programming style that determines an object's type by inspection

19
Doc/reference/compound_stmts.rst
View File

@ -422,7 +422,7 @@ reference to the current global namespace as the global namespace to be used
when the function is called.
The function definition does not execute the function body; this gets executed
only when the function is called.
only when the function is called. [#]_
.. index::
statement: @
@ -509,6 +509,7 @@ Class definitions
pair: name; binding
pair: execution; frame
single: inheritance
single: docstring
A class definition defines a class object (see section :ref:`types`):
@ -523,10 +524,10 @@ to a class object or class type which allows subclassing. The class's suite is
then executed in a new execution frame (see section :ref:`naming`), using a
newly created local namespace and the original global namespace. (Usually, the
suite contains only function definitions.) When the class's suite finishes
execution, its execution frame is discarded but its local namespace is saved. A
class object is then created using the inheritance list for the base classes and
the saved local namespace for the attribute dictionary. The class name is bound
to this class object in the original local namespace.
execution, its execution frame is discarded but its local namespace is
saved. [#]_ A class object is then created using the inheritance list for the
base classes and the saved local namespace for the attribute dictionary. The
class name is bound to this class object in the original local namespace.
**Programmer's note:** Variables defined in the class definition are class
variables; they are shared by all instances. To create instance variables, they
@ -551,3 +552,11 @@ which is then bound to the class name.
.. [#] Currently, control "flows off the end" except in the case of an exception or the
execution of a :keyword:`return`, :keyword:`continue`, or :keyword:`break`
statement.
.. [#] A string literal appearing as the first statement in the function body is
transformed into the function's ``__doc__`` attribute and therefore the
function's :term:`docstring`.
.. [#] A string literal appearing as the first statement in the class body is
transformed into the namespace's ``__doc__`` item and therefore the class's
:term:`docstring`.