[Zope3-Users] How to find something in the apidoc ?

[Stephan Richter]

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