On 3/15/06, Martijn Faassen <[EMAIL PROTECTED]> 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 _______________________________________________ Zope3-dev mailing list Zope3email@example.com Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com