[Twisted-Python] Re: [Twisted-web] Re: Actual Useful Post
Michael Hudson
mwh at python.net
Mon Jan 23 12:14:32 EST 2006
Andrew Bennetts <andrew-twisted at puzzling.org> writes:
> [moving this to twisted-python, where it clearly belongs]
>
> Michael Hudson wrote:
> [...]
>>
>> Well, I've had a quick pop at the interesting bit of this task while
>> travelling over the weekend: using the compiler module I can extract
>> the docstrings and class hierachy of all the stuff in the Twisted
>> source. It's a touch fragile, but seems to work for all the
>> constructions used by Twisted.
>>
>> One issue is classes that are defined in one file but generally used
>> from another, for example twisted.spread.jelly.Serializable is often
>> (always?) imported as twisted.spread.pb.Serializable. Where should it
>> be documented it?
>
> See http://twistedmatrix.com/bugs/issue1143. It has the possibly useful
> suggestion of using __all__ to determine where an aliased thing should be
> documented.
Hmm, that could work. Although having the "official" name for a class
different from its __name__ is fairly horrible :)
> Another option is some sort of explicit hint to the doc extractor, e.g. a define
> no-op call like "alias('Serializable')" in the relevant module that the doc
> extractor could notice. Or keep an explicit list of overrides in a file...
These also could work, as could magic comments (though that would be
marginally harder).
Cheers,
mwh
--
What the semicolon's anxious supporters fret about is the tendency
of contemporary writers to use a dash instead of a semicolon and
thus precipitate the end of the world.
-- Lynne Truss, "Eats, Shoots & Leaves"
More information about the Twisted-Python
mailing list