[Grok-dev] Naming of grok.provides

[Kevin Teague]

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.

But even with clearer documentation it's still somewhat confusing?  
Maybe grok.registers is clearer? 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.

(I think that makes sense? not quite sure - I've been travelling all  
day after the PloneConf and am quite tired.)