More minor documentation fixups.

Mostly formatting. Some interfaces were being documented as clasess, which doesn't work.

CHANGES.rst

@@ -5,16 +5,6 @@
 5.0.0 (unreleased)
 ==================
 
-- Adopt Python's standard `C3 resolution order
-  <https://www.python.org/download/releases/2.3/mro/>`_ for interface
-  linearization, with tweaks to support additional cases that are
-  common in interfaces but disallowed for Python classes.
-
-  In complex multiple-inheritance like scenerios, this may change the
-  interface resolution order, resulting in finding different adapters.
-  However, the results should make more sense. See `issue 21
-  <https://github.com/zopefoundation/zope.interface/issues/21>`_.
-
 - Make an internal singleton object returned by APIs like
   ``implementedBy`` and ``directlyProvidedBy`` immutable. Previously,
   it was fully mutable and allowed changing its ``__bases___``. That
@@ -57,6 +47,12 @@
   The changes in this release resulted in a 7% memory reduction after
   loading about 6,000 modules that define about 2,200 interfaces.
 
+  .. caution::
+
+     Details of many private attributes have changed, and external use
+     of those private attributes may break. In particular, the
+     lifetime and default value of ``_v_attrs`` has changed.
+
 - Remove support for hashing uninitialized interfaces. This could only
   be done by subclassing ``InterfaceClass``. This has generated a
   warning since it was first added in 2011 (3.6.5). Please call the
@@ -162,9 +158,12 @@
 - Fix a potential interpreter crash in the low-level adapter
   registry lookup functions. See issue 11.
 
-- Use Python's standard C3 resolution order to compute the
-  ``__iro___`` and ``__sro___`` of interfaces. Previously, an ad-hoc
-  ordering that made no particular guarantees was used.
+- Adopt Python's standard `C3 resolution order
+  <https://www.python.org/download/releases/2.3/mro/>`_ to compute the
+  ``__iro___`` and ``__sro___`` of interfaces, with tweaks to support
+  additional cases that are common in interfaces but disallowed for
+  Python classes. Previously, an ad-hoc ordering that made no
+  particular guarantees was used.
 
   This has many beneficial properties, including the fact that base
   interface and base classes tend to appear near the end of the

docs/api/specifications.rst

@@ -197,14 +197,17 @@ content, or body, of an ``Interface``.
 
 .. autointerface:: zope.interface.interfaces.IAttribute
 .. autoclass:: zope.interface.interface.Attribute
+   :no-members:
 
-.. autoclass:: IMethod
+.. autointerface:: IMethod
+.. autoclass:: zope.interface.interface.Method
+   :no-members:
 
 Finally we can look at the definition of ``IInterface``.
 
 .. autointerface:: IInterface
 
-.. autoclass:: zope.interface.Interface
+.. autointerface:: zope.interface.Interface
 
 Usage
 -----

src/zope/interface/interfaces.py

@@ -150,25 +150,26 @@ class IMethod(IAttribute):
     def getSignatureInfo():
         """Returns the signature information.
 
-        This method returns a dictionary with the following keys:
+        This method returns a dictionary with the following string keys:
 
-        o `positional` - All positional arguments.
-
-        o `required` - A list of all required arguments.
-
-        o `optional` - A list of all optional arguments.
-
-        o `varargs` - The name of the varargs argument.
-
-        o `kwargs` - The name of the kwargs argument.
+        - positional
+            A sequence of the names of positional arguments.
+        - required
+            A sequence of the names of required arguments.
+        - optional
+            A dictionary mapping argument names to their default values.
+        - varargs
+            The name of the varargs argument (or None).
+        - kwargs
+            The name of the kwargs argument (or None).
         """
 
     def getSignatureString():
         """Return a signature string suitable for inclusion in documentation.
 
         This method returns the function signature string. For example, if you
-        have `func(a, b, c=1, d='f')`, then the signature string is `(a, b,
-        c=1, d='f')`.
+        have ``def func(a, b, c=1, d='f')``, then the signature string is ``"(a, b,
+        c=1, d='f')"``.
         """
 
 class ISpecification(Interface):