[Epydoc-devel] Easier class names lookup

[Daniele V. <pi...@de...>]

Hello,

in r1448 i added a fallback rule for the DocIndex.find() method: if a class 
name is looked for, and such class has not been imported into the namespace it 
is referred from, then look for it into the documented modules. The class is 
returned only if its name is not ambiguous: if there exist more classes with 
the same name, a warning is emitted.

The implemented check is efficient: about a single non recursive scan of all 
the documented modules to create a map from names to classes, and a dict 
lookup for each name that would have failed with the previous find() 
implementation.

The rationale behind this rule is that in Python you don't have to know an 
object class in order to use it, as long as you receive an instance and you 
trust the caller he sent you a duck with the right number of legs. So people 
ends up writing:

class Bar:
     def shootProtons(self, foo):
         """Frobnicate the world

         :Parameters:
           `foo` : `Foo`
             the required frobnicator
         """
         foo.shoot()

It often happens that Foo is defined in another module. If Foo were not 
imported in the module defining Bar, Epydoc would have failed linking `Foo` to 
the Foo class documentation.

To overcome this it is possible to import the object in the namespace:

     from foomodule import Foo

but if foomodule happens to use objects defined in the barmodule, there would 
be a cross modules import doomed to fail.

Another alternative is to import the containing module:

     import foomodule

but then the class should be referred as `foomodule.Foo` and, in case of 
refactoring all the references were to be updated; Furthermore the modules 
would be paired even if the code wouldn't require it.

Yet another alternative would be to import all the classes in the __init__.py 
of the main package, but often you don't *need* them there, and this would 
block lazy imports.

In a more generic sense, Epydoc should not ask the source to be adapted to be 
handled: it's fine to adapt docstrings, but code shouldn't be affected.

-- 
Daniele Varrazzo - Develer S.r.l.
http://www.develer.com