[Python-Dev] Pydoc Improvements / Rewrite

Robert Kern robert.kern at gmail.com
Sat Jan 6 09:41:04 CET 2007


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



More information about the Python-Dev mailing list