[Zope3-dev] Re: a new zcml directive?

[Jeff Shell]

On 3/15/06, Martijn Faassen <faassen at infrae.com> wrote:
> In the new world for ZCML, ZCML as a language falls apart in a
> minimalistic XML language, and some support code (such as
> zope.app.annotation.AnnotationFactory) to help it do more advanced things.

That's what I'd like to see! :)

> One remaining benefit of higher-level ZCML is that it gets picked up by
> apidoc and thus can be discovered fairly easily by developers as part of
> the configuration story. While AnnotationFactory is doing definition and
> is in Python code in the new world for ZCML, this act of definition is
> closely associated with the act of registering it in ZCML.

I agree with that benefit of higher-level ZCML. But I've found in
practice that documentation is still terse and sparse. That alone is
what has had me digging into the code to try to figure out "ok, what
does that mean?"

    name - TextLine (default = None)
    Name
    Adapters can have names.

    This attribute allows you to specify the name for this adapter.

So, yay for documentation. That bit's good. But things like this could
really really benefit from some examples. Especially on core things
like adapter, whose 'locate', 'permission', and 'trusted' properties
and their impact on each other are a bit tricky to figure out.

But Python code and interfaces get picked up by apidoc too. Well, most
of them (schema fields have gone missing in action.. I think a search
will turn them up, but they can't be browsed to directly).

One of the biggest downsides of higher-level ZCML to me is that it
feels totally disconnected from Python. The documentation, as it
stands now, generally documents the fields. But it doesn't go into
what's being done behind the scenes, or why I should be using
directive X, or how to use the results of directive X. The other
downside is that higher level ZCML needs the ZCML 'runtime' in order
to work.

Besides, AnnotationFactory isn't just associated with registering
something in ZCML. It can be associated with registering something
with::

    zope.component.provideAdapter(...)

I know that the adapter directive does a bit more than just provide an
adapter. But the point is that it could be used outside of ZCML.

> It would be nice if we somehow retained discoverability for APIs that
> are meant to work with ZCML - it's obvious from this subthread that it
> takes some idiots^H^H^H^H^H^Hpeople a while to pick up an API... We'd
> like people working with annotations to be able to find out that we have
> this available. Perhaps a README.txt in the annotation package is enough
> for now, though. Perhaps we can think of other ways to help make this
> discoverable...

I don't know the status of the static-apidoc tool, but maybe that
could help in some ways...

By having http://api.rubyonrails.com/ , not only is there a great
online API reference, but it's (of course) searchable by the search
engine of choice. Hopefully there will be a day when a search for
'zope annotations' will have the API reference and a couple of darn
good recipes/articles/tips as the first set of results. I know it's
been helpful to see a reference to something in Rails and google
``rails validates_presence_of`` and usually get to the api reference
first. (Not that I'm leaving Zope for Rails, but I have been toying
with it a bit, I admit).

--
Jeff Shell