Update documentation and Provides repr for better debugging.

[jamadden]

Fixes #229.

Replaces #232

[icemac]

Mostly LGTM.

[icemac]

I'd prefer to see the complete text here. Is this possible?
Currently the test seems to be is nearly a repetition of the code in the method under test.

[jamadden]

Great point. I'll make a change.

[jamadden]

Given spec = Provides(AClass, IFoo, IBar), the repr will be something like

<zope.interface.Provides for instances of <class 'some.module.AClass'> providing (<InterfaceClass some.module.interfaces.IFoo>, <InterfaceClass some.module.interfaces.IBar>)>

Informative, but not terse.

Basically none of these objects have a __str__ method.

__repr__ is meant to "look like a valid Python expression that could be used to recreate an object with the same value (given an appropriate environment)."

In contrast __str__ computes "the 'informal' string representation of an object. This differs from __repr__() in that it does not have to be a valid Python expression: a more convenient or concise representation may be used instead. The return value must be a string object."

For Provides, it would be pretty easy to give a repr that actually can be evaluated (in many cases) outputting something like

Provides(AClass, IFoo, IBar)

Similarly, interfaces could have a __str__ that just outputs __module__.__name__.

That would transform reports from

Object <InterfaceClass BTrees.Interfaces.ISet> has different legacy and C3 MROs:
  Legacy RO (len=7)                                  C3 RO (len=7; inconsistent=no)
  ====================================================================================================
    <InterfaceClass BTrees.Interfaces.ISet>            <InterfaceClass BTrees.Interfaces.ISet>
    <InterfaceClass BTrees.Interfaces.IKeySequence>    <InterfaceClass BTrees.Interfaces.IKeySequence>
  - <InterfaceClass BTrees.Interfaces.ISized>
    <InterfaceClass BTrees.Interfaces.ISetMutable>     <InterfaceClass BTrees.Interfaces.ISetMutable>
    <InterfaceClass BTrees.Interfaces.IKeyed>          <InterfaceClass BTrees.Interfaces.IKeyed>
    <InterfaceClass BTrees.Interfaces.ICollection>     <InterfaceClass BTrees.Interfaces.ICollection>
                                                     + <InterfaceClass BTrees.Interfaces.ISized>
    <InterfaceClass zope.interface.Interface>          <InterfaceClass zope.interface.Interface>

to

Object <InterfaceClass BTrees.Interfaces.ISet> has different legacy and C3 MROs:
  Legacy RO (len=7)                                  C3 RO (len=7; inconsistent=no)
  ==================================================================================
    BTrees.Interfaces.ISet            BTrees.Interfaces.ISet
    BTrees.Interfaces.IKeySequence    BTrees.Interfaces.IKeySequence
  - BTrees.Interfaces.ISized
    BTrees.Interfaces.ISetMutable     BTrees.Interfaces.ISetMutable
    BTrees.Interfaces.IKeyed          BTrees.Interfaces.IKeyed
    BTrees.Interfaces.ICollection     BTrees.Interfaces.ICollection
                                    + BTrees.Interfaces.ISized
    zope.interface.Interface          zope.interface.Interface

(With similar benefits when Provides is present.)

Since the changes in Provides here mean that there might have to be doctest updates, and since adding a __str__ mostly shouldn't (but might!) cause doctest updates, this might be a good time to make such a change.

What do you think?

[jamadden]

Moved discussion to issue #236.

[jamadden]

Thanks for the review!