[Twisted-Python] Pydoc parameter formatting and explaining interfaces

Glyph Lefkowitz glyph at twistedmatrix.com
Tue Jul 26 11:58:19 MDT 2016


> On Jul 26, 2016, at 9:37 AM, Daniel Sank <sank.daniel at gmail.com> wrote:
> 
> 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 <https://github.com/twisted/pydoctor/issues/121>

Thanks!  I especially appreciate the screen shot :).

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

For me it's a monty python reference, but I suspect for most speakers of British English, it's just an idiom :).  It roughly means "mea culpa", although, more specifically, I believe it means "you've caught me doing something bad".

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

Please direct my attention to it when one exists :).

-glyph
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20160726/331aafd6/attachment-0002.html>


More information about the Twisted-Python mailing list