> On Jul 26, 2016, at 9:37 AM, Daniel Sank <sank.dan...@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
_______________________________________________
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
