[Twisted-Python] Re: [Twisted-web] Re: Actual Useful Post

[Jean-Paul Calderone]

On Mon, 23 Jan 2006 17:14:32 +0000, Michael Hudson <mwh at python.net> wrote:
>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.

+1 for using a mechanism associated with an existing Python idiom

>
>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).

-1 for magic markup embedded in source files

Jean-Paul