[Python-checkins] cpython (2.7): Improve glossary entry for ABCs.

[eric.araujo]

http://hg.python.org/cpython/rev/d62d7604ce5a
changeset:   71581:d62d7604ce5a
branch:      2.7
user:        Éric Araujo <merwok at netwok.org>
date:        Fri Jul 29 11:34:17 2011 +0200
summary:
  Improve glossary entry for ABCs.

- Rename reST target name for collections ABCs to avoid collisions
- Link to glossary entry from numbers module doc (other modules already do it)

files:
  Doc/glossary.rst            |  11 ++++++-----
  Doc/library/abc.rst         |   4 ++--
  Doc/library/collections.rst |  11 ++++++-----
  Doc/library/numbers.rst     |   6 +++---
  4 files changed, 17 insertions(+), 15 deletions(-)


diff --git a/Doc/glossary.rst b/Doc/glossary.rst
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -27,12 +27,13 @@
       :ref:`2to3-reference`.
 
    abstract base class
-      :ref:`abstract-base-classes` complement :term:`duck-typing` by
+      Abstract base classes complement :term:`duck-typing` by
       providing a way to define interfaces when other techniques like
-      :func:`hasattr` would be clumsy. Python comes with many built-in ABCs for
+      :func:`hasattr` would be clumsy or subtly wrong (for example with
+      :ref:`magic methods <new-style-special-lookup>`). Python comes with many built-in ABCs for
       data structures (in the :mod:`collections` module), numbers (in the
       :mod:`numbers` module), and streams (in the :mod:`io` module). You can
-      create your own ABC with the :mod:`abc` module.
+      create your own ABCs with the :mod:`abc` module.
 
    argument
       A value passed to a function or method, assigned to a named local
@@ -424,8 +425,8 @@
    mapping
       A container object that supports arbitrary key lookups and implements the
       methods specified in the :class:`Mapping` or :class:`MutableMapping`
-      :ref:`abstract base classes <abstract-base-classes>`. Examples include
-      :class:`dict`, :class:`collections.defaultdict`,
+      :ref:`abstract base classes <collections-abstract-base-classes>`.  Examples
+      include :class:`dict`, :class:`collections.defaultdict`,
       :class:`collections.OrderedDict` and :class:`collections.Counter`.
 
    metaclass
diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst
--- a/Doc/library/abc.rst
+++ b/Doc/library/abc.rst
@@ -9,8 +9,8 @@
 
 .. versionadded:: 2.6
 
-This module provides the infrastructure for defining an :term:`abstract base
-class` (ABCs) in Python, as outlined in :pep:`3119`; see the PEP for why this
+This module provides the infrastructure for defining :term:`abstract base
+classes <abstract base class>` (ABCs) in Python, as outlined in :pep:`3119`; see the PEP for why this
 was added to Python. (See also :pep:`3141` and the :mod:`numbers` module
 regarding a type hierarchy for numbers based on ABCs.)
 
diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -28,7 +28,7 @@
 =====================   ====================================================================  ===========================
 
 In addition to the concrete container classes, the collections module provides
-:ref:`abstract-base-classes` that can be used to test whether a class provides a
+:ref:`collections-abstract-base-classes` that can be used to test whether a class provides a
 particular interface, for example, whether it is hashable or a mapping.
 
 .. seealso::
@@ -851,8 +851,8 @@
 original insertion position is changed and moved to the end::
 
     class LastUpdatedOrderedDict(OrderedDict):
+        'Store items in the order the keys were last added'
 
-        'Store items in the order the keys were last added'
         def __setitem__(self, key, value):
             if key in self:
                 del self[key]
@@ -871,10 +871,10 @@
             return self.__class__, (OrderedDict(self),)
 
 
-.. _abstract-base-classes:
+.. _collections-abstract-base-classes:
 
-ABCs - abstract base classes
-----------------------------
+Collections Abstract Base Classes
+---------------------------------
 
 The collections module offers the following :term:`ABCs <abstract base class>`:
 
@@ -888,7 +888,7 @@
 :class:`Sized`                                    ``__len__``
 :class:`Callable`                                 ``__call__``
 
-:class:`Sequence`          :class:`Sized`,        ``__getitem__``         ``__contains__``. ``__iter__``, ``__reversed__``,
+:class:`Sequence`          :class:`Sized`,        ``__getitem__``         ``__contains__``, ``__iter__``, ``__reversed__``,
                            :class:`Iterable`,                             ``index``, and ``count``
                            :class:`Container`
 
diff --git a/Doc/library/numbers.rst b/Doc/library/numbers.rst
--- a/Doc/library/numbers.rst
+++ b/Doc/library/numbers.rst
@@ -7,9 +7,9 @@
 .. versionadded:: 2.6
 
 
-The :mod:`numbers` module (:pep:`3141`) defines a hierarchy of numeric abstract
-base classes which progressively define more operations.  None of the types
-defined in this module can be instantiated.
+The :mod:`numbers` module (:pep:`3141`) defines a hierarchy of numeric
+:term:`abstract base classes <abstract base class>` which progressively define
+more operations.  None of the types defined in this module can be instantiated.
 
 
 .. class:: Number

-- 
Repository URL: http://hg.python.org/cpython