Phillip J. Eby wrote:
> 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.
FWIW, a 3.0a3 was released in August 2006, and according to the History,
"Significant portions of epydoc were written for version 3.0." It seems a lot of
that was to add parsing as a complementary means to extract documentation. I'm
not particularly familiar with the introspection code of either 2.1 or 3.0a3,
but a cursory examination shows that 3.0a3 has an introspecter registry that 2.1
doesn't:
# In epydoc.docintrospecter:
def register_introspecter(applicability_test, introspecter, priority=10):
"""
Register an introspecter function. Introspecter functions take
two arguments, a python value and a C{ValueDoc} object, and should
add information about the given value to the the C{ValueDoc}.
Usually, the first line of an inspecter function will specialize
it to a sublass of C{ValueDoc}, using L{ValueDoc.specialize_to()}:
>>> def typical_introspecter(value, value_doc):
... value_doc.specialize_to(SomeSubclassOfValueDoc)
... <add info to value_doc>
@param priority: The priority of this introspecter, which determines
the order in which introspecters are tried -- introspecters with lower
numbers are tried first. The standard introspecters have priorities
ranging from 20 to 30. The default priority (10) will place new
introspecters before standard introspecters.
"""
--
Robert Kern
"I have come to believe that the whole world is an enigma, a harmless enigma
that is made terrible by our own mad attempt to interpret it as though it had
an underlying truth."
-- Umberto Eco
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
