[Python-Dev] Pydoc Improvements / Rewrite
Phillip J. Eby
pje at telecommunity.com
Sat Jan 6 09:09:13 CET 2007
At 12:16 AM 1/6/2007 -0500, Barry Warsaw wrote:
>If you've already explained it, that's fine, but if not, could you
>outline what you have against epydoc?
The last I tried to work with it, it had even more hardcoded typechecking
than pydoc does, spread out over more of the code base. Also, over at
OSAF, I've been repeatedly called upon to sort out some peculiarity in how
it discovers things or how it handles types it doesn't recognize.
My net impression has been that it's very brittle, even more so than pydoc.
On the plus side, there are some very good ideas and a *lot* of good
execution in there, but its extensibility has historically struck me as
non-existent.
To be fair, the last time I had to deal with any problems with it at OSAF
was almost a year ago, if memory serves. I don't know if anything has
improved in it since then.
The last time I seriously analyzed its internal architecture was several
years ago (maybe 5?) when I was investigating it as an alternative to
HappyDoc for doing PEAK's API documentation. I could never get it to work
on anything but a small subset of PEAK without crashing in any of several
ways, including segfaulting its GUI! It had built into it a variety of
restrictive assumptions about how programs are structured that were not
compatible with what I was doing. pydoc at least only crashed when dealing
with metaclass instances, but I believe that was fixed in 2.3 or a late
2.2.x release.
Anyway, I like the *idea* of epydoc and a lot of its execution, but IMO it
needs just as much work as pydoc, if not more.
More information about the Python-Dev
mailing list