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
|
