[Twisted-Python] Pydoc parameter formatting and explaining interfaces

Daniel Sank sank.daniel at gmail.com
Tue Jul 26 10:37:29 MDT 2016


This is a branch from the thread with subject "Request for help with
Twisted bindings in M2Crypt".

Regarding my inability to read documentation:

> This does at least point to a real problem with pydoctor in the way it
presents types.
> It should probably put them in their own colored box, not use the string
'type' or
> parentheses to offset them, and put the type closer to (rather than
farther from) the
> parameter name.  Would you mind filing a bug on pydoctor?  Or commenting
on
> one if it already exists? :)

Done: https://github.com/twisted/pydoctor/issues/121

>> Some years ago when I tried to understand Twisted's use of interfaces
via Twisted's
>> own documentation (which included something about hair dryers and
voltage standards)
>> I was puzzled by the fact that the examples didn't really show me how to
solve a useful
>> problem (or I was too stupid to understand that the examples did in fact
do that) despite
>> the fact that I knew what an interface was in general terms. It was a
case of
>> understanding the intent but none of the examples.

> OK... it's a fair cop.

I'm unfamiliar with that term.

> Among other things, it's mainly trying to explain adaptation, which sort
of puts the cart before
> the horse

Yes! That is definitely a big part of the problem. When I think "interface"
I think "methods and their signatures an object promises to provided".
Adaptation is a detail, so to speak. It's also somewhat confusing that the
discussion begins with shapes as it goes over the basic idea of interfaces,
and then switches to hair dryers when it comes time for an example. It
would be easier to read if the examples were more consistent.

> and automatic adaptation is increasingly considered spooky
action-at-a-distance within
> Twisted code.

All the more reason to not use adaptation as the in-your-face example.

> You're the perfect person to submit patches against this doc, by the way,
since you have a
> firm grasp of the whole "abstract interface" thing but also found it
confusing.

Perhaps. On the other hand I think it might be better to replace Twisted's
own documentation with a link to zope's, or at least put the link at the
top and say "read this before reading our examples about adaptation." We'll
see if such a patch receives any love.

--
Daniel Sank
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://twistedmatrix.com/pipermail/twisted-python/attachments/20160726/caa860f0/attachment.html>


More information about the Twisted-Python mailing list