From e64f7385073028f4e916c4eb12342ecb91c50884 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 20 Jul 2008 11:50:29 +0000 Subject: #926501: add info where to put the docstring. --- Doc/glossary.rst | 8 ++++++++ Doc/reference/compound_stmts.rst | 19 ++++++++++++++----- 2 files changed, 22 insertions(+), 5 deletions(-) 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 @@ 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 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 @@ 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`. -- cgit v0.12