[Grok-dev] Naming of grok.provides

[Philipp von Weitershausen]

Kevin Teague wrote:
> On Oct 12, 2008, at 11:19 PM, Thomas Lotze wrote:
> 
>> We recently noticed that the grok.provides directive is not well- 
>> named:
>>
>> The documentation states that "if the local utility implements
>> more than one interface or if the implemented interface cannot be
>> determined, grok.provides() is required to disambiguate for what
>> interface the local utility will be registered."
>>
>> OTOH, in zope.interface terminology, the term "provides" has a clear
>> meaning in contrast to "implements": if a class, for instance,
>> implements a certain interface, its instances are said to provide it.
>>
>> We feel that something should be done about this contradiction of
>> terminologies as it confuses not only newcomers to Grok. Beyond a
>> documentation improvement, what would be an acceptable fix given that
>> this directive is rather close to Grok's core?
>>
> 
> Yeah, the text in the Grok Reference docs is even more confusing (and  
> wrong ... although I think I wrote that.). I've just updated that text  
> to read:
> 
> :func:`grok.provides` -- disambiguate which interface is registered
> ===================================================
> 
> .. function:: grok.provides(interface)
> 
>      Explicitly specify with which interface a component will be
>      looked up. If a class declares that it implements several  
> interaces,
>      :func:`grok.provides` can be used to disambiguate which interface  
> will be
>      registered with the Zope Component Architecture.

That's a pretty good definition. Thanks!

> But even with clearer documentation it's still somewhat confusing?  
> Maybe grok.registers is clearer? 

Or grok.register_for(). Consider this example::

   class FooBar(grok.GlobalUtility):
       grok.implements(IBar, IFoo)
       grok.register_for(IFoo)

> Since any class implements many  
> interfaces that is used to create a component, that component is going  
> to provide many interfaces - it's just used to state which interface  
> is registered with the CA that it's interested in as providing for the  
> CA among the many it provides.

Right. I think we chose the name grok.provides() initially because the 
keyword parameter of the registrations functions in zope.component is 
called "provides". That's a poor excuse, of course.