[Grok-dev] Naming of grok.provides
Kevin Teague
kevin at bud.ca
Tue Oct 14 01:44:33 EDT 2008
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.)
More information about the Grok-dev
mailing list