On Sunday 08 October 2006 09:06, Christophe Combelles wrote:
Hi,
the /++apidoc++ is the main and greatest source of documentation for the
zope 3 API, but sometimes I spend a lot of time to find something. So I
have 3 questions:
Take an example: Say I've heard about the function getMultiAdapter, and I
want to know how to use it. So I first go to the apidoc and:
1) if I don't know which component this function is part of, how do I
quickly find it?
You can't at the moment. There is no generic search feature at this point.
Actually you can easily search for packages, modules, and classes using the
Code Browser, but not functions and methods. Maybe we should create an
efficient index to search these things too? I would be happy for a detailed
proposal of the features users would like to see for the code browser.
Then I find two code examples calling it, one from
zope.component.getMultiAdapter, and the other from
zope.app.zapi.getMultiAdapter
Right, both will work. They are exactly the same function. However, we will
eventually deprecate zope.app.zapi altogether.
2) How can I know which one to use, and whether they're identical or not?
To be sure, I go to the Code Browser: I click on zope, then on
component. Here, nothing that looks like getMultiAdapter. I guess this
function is defined in an interface, so I click on interfaces and I find
at least 15 interfaces. After 5 more minutes, I finally find the function
in IComponentArchitecture.
The problem here is that the API is hidden in some deferred import magic that
apidoc cannot resolve further.
I do the same for zope.app.zapi but this time it's easier since there is
only one interface zope.app.zapi.interfaces.IZAPI in which I can find the
wanted getMultiAdapter function.
Another more difficult example: zope.schema.getFields().
When you go to zope-schema-interfaces, there are 57 entries. Where is
getFields()? And is it related to zope.app.apidoc.interface.getFields() ?
Again, I would like to see some concrete suggestions on how things can be
improved. Note that APIDOC cannot do magic, but it tries very hard to collect
and organize every bit of useful information.
So my last question is:
3) How can I quickly find zope.something.example.function in the doc ?
Ditto to 1.
Regards,
Stephan
--
Stephan Richter
CBU Physics Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training
___
Zope3-users mailing list
Zope3-users@zope.org
http://mail.zope.org/mailman/listinfo/zope3-users
