#926501: add info where to put the docstring.
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index fc55d1f..81e29f1 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -123,6 +123,14 @@
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
diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst
index b9b5689..0794755 100644
--- a/Doc/reference/compound_stmts.rst
+++ b/Doc/reference/compound_stmts.rst
@@ -422,7 +422,7 @@
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 @@
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 @@
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 @@
.. [#] 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`.