Make Interface.getTaggedValue follow the __iro__.

Previously it manually walked up __bases__, meaning the answers could be inconsistent.

Fixes #190.

Also fixes several minor issues in the documentation, mostly cross-reference related.

3 files changed, 43 insertions, 5 deletions

diff --git a/docs/README.rst b/docs/README.rst
index d1e58cf..a8068f8 100644
--- a/docs/README.rst
+++ b/docs/README.rst
@@ -736,6 +736,28 @@ Tagged values can also be defined from within an interface definition:
   >>> IWithTaggedValues.getTaggedValue('squish')
   'squash'
 
+Tagged values are inherited in the same way that attribute and method
+descriptions are. Inheritance can be ignored by using the "direct"
+versions of functions.
+
+.. doctest::
+
+   >>> class IExtendsIWithTaggedValues(IWithTaggedValues):
+   ...     zope.interface.taggedValue('child', True)
+   >>> IExtendsIWithTaggedValues.getTaggedValue('child')
+   True
+   >>> IExtendsIWithTaggedValues.getDirectTaggedValue('child')
+   True
+   >>> IExtendsIWithTaggedValues.getTaggedValue('squish')
+   'squash'
+   >>> print(IExtendsIWithTaggedValues.queryDirectTaggedValue('squish'))
+   None
+   >>> IExtendsIWithTaggedValues.setTaggedValue('squish', 'SQUASH')
+   >>> IExtendsIWithTaggedValues.getTaggedValue('squish')
+   'SQUASH'
+   >>> IExtendsIWithTaggedValues.getDirectTaggedValue('squish')
+   'SQUASH'
+
 Invariants
 ==========
 
diff --git a/docs/api/declarations.rst b/docs/api/declarations.rst
index ce52833..26847b0 100644
--- a/docs/api/declarations.rst
+++ b/docs/api/declarations.rst
@@ -16,7 +16,7 @@ carefully at each object it documents, including providing examples.
 .. autointerface:: zope.interface.interfaces.IInterfaceDeclaration
 
 
-.. currentmodule:: zope.interface.declarations
+.. currentmodule:: zope.interface
 
 Declaring The Interfaces of Objects
 ===================================
@@ -536,7 +536,7 @@ You'll notice that an ``IDeclaration`` is a type of
 implementedBy
 -------------
 
-.. autofunction:: implementedByFallback
+.. autofunction:: implementedBy
 
 
 Consider the following example:
@@ -774,7 +774,7 @@ Exmples for :meth:`Declaration.__add__`:
 ProvidesClass
 -------------
 
-.. autoclass:: ProvidesClass
+.. autoclass:: zope.interface.declarations.ProvidesClass
 
 
 Descriptor semantics (via ``Provides.__get__``):
@@ -851,7 +851,7 @@ collect function to help with this:
 ObjectSpecification
 -------------------
 
-.. autofunction:: ObjectSpecification
+.. autofunction:: zope.interface.declarations.ObjectSpecification
 
 
 For example:
@@ -924,7 +924,7 @@ For example:
 ObjectSpecificationDescriptor
 -----------------------------
 
-.. autoclass:: ObjectSpecificationDescriptor
+.. autoclass:: zope.interface.declarations.ObjectSpecificationDescriptor
 
 For example:
 
diff --git a/docs/api/specifications.rst b/docs/api/specifications.rst
index 2152e26..53b0ab7 100644
--- a/docs/api/specifications.rst
+++ b/docs/api/specifications.rst
@@ -23,6 +23,7 @@ Specification objects implement the API defined by
    :member-order: bysource
 
 .. autoclass:: zope.interface.interface.Specification
+   :no-members:
 
 For example:
 
@@ -172,7 +173,22 @@ first is that of an "element", which provides us a simple way to query
 for information generically (this is important because we'll see that
 ``IInterface`` implements this interface):
 
+..
+  IElement defines __doc__ to be an Attribute, so the docstring
+  in the class isn't used._
+
 .. autointerface:: IElement
+
+   Objects that have basic documentation and tagged values.
+
+   Known derivatives include :class:`IAttribute` and its derivative
+   :class:`IMethod`; these have no notion of inheritance.
+   :class:`IInterface` is also a derivative, and it does have a
+   notion of inheritance, expressed through its ``__bases__`` and
+   ordered in its ``__iro__`` (both defined by
+   :class:`ISpecification`).
+
+
 .. autoclass:: zope.interface.interface.Element
    :no-members: