Write a howto documenting endpoints

[itamar]

Now that we have the new feature in place, endpoints could do with some documentation for users.

[glyph]

For the reasons discussed on #4320 this should probably be a priority for the release.

[exarkun]

(In [29279]) Branching to 'endpoints-docs-4478'

[glyph]

(In [29287]) Well, it's something. As with much Twisted documentation it's hard to come up with a sufficient amount of context. Also, there isn't really a lot you can do with an endpoint by itself...

I've documented the strports stuff under the names currently used in the #4473 branch, but this will obviously have to change if they do.

refs #4473

refs #4478

[jml]

Twisted 10.1.0 has been released. Removing this ticket from the 10.1 milestone. If you think it's severe enough to demand a follow-up release, please say so and add this ticket back to the 10.1 milestone.

[glyph]

(In [30157]) Branching to 'endpoints-docs-4478-2'

[exarkun]

1. clients.xhtml
   1. The sentence "An important advantage of the endpoint API ..." doesn't entirely make sense in contenxt. Nothing else has been introduced to have advantages over. One might suppose that this is an advantage over using sockets directly, but I don't think that's actually the intent here. I would suggest changing the word "advantage" to "feature".
   2. "For more information on different ways you can listen for incoming connections, see the documentation for the endpoints API." should be talking about connecting instead of listening.
2. endpoints.xhtml
   1. "For example, a very simple 30-second timeout could be

implemented like this:" - does it really get to be this simple? What about canceling the delayed call?

1. The conclusion is a bit weak. But don't let that stop you from merging the branch. We can always beef it up later.

Please merge when these are addressed to your satisfaction.

[exarkun]

Also, news fragment.

[glyph]

(In [30269]) Add documentation for endpoints API.

Author: glyph

Reviewer: exarkun

Fixes: #4478

This adds narrative documentation for twisted.internet.endpoints, as well as updating the existing documentation for writing clients and servers to point to the shiny new APIs.

[glyph]

Replying to exarkun:

The sentence "An important advantage of the endpoint API ..." doesn't entirely make sense in contenxt. Nothing else has been introduced to have advantages over. One might suppose that this is an advantage over using sockets directly, but I don't think that's actually the intent here. I would suggest changing the word "advantage" to "feature".

I tried to re-work the paragraph to actually describe the feature, rather than how you use the feature, and without reference to the 'old' API. I also updated some other mentions of the 'old' API to refer to the 'low-level' API instead.

"For more information on different ways you can listen for incoming connections, see the documentation for the endpoints API." should be talking about connecting instead of listening.

Fixed, good catch.

"For example, a very simple 30-second timeout could be implemented like this:" - does it really get to be this simple? What about canceling the delayed call?

I thought about this a bit, and yeah, I think it does actually get to be that simple. If you're writing a trial unit test, you care because of the dirty reactor error, but that's not what this documentation is about. If you cancel a Deferred which has been called back already, you don't get an exception. Consider:

>>> from twisted.internet.defer import Deferred
>>> d = Deferred()
>>> d.callback(1)
>>> d.cancel()
>>> del d

The conclusion is a bit weak. But don't let that stop you from merging the branch. We can always beef it up later.

I agree, but I think that nailing down what about it is weak and trying to come up with a better narrative is potentially a big change, maybe even leading into a separate document. Maybe that document is about endpoint type plugins. Let's talk about it more and file a follow-up ticket when we have a good idea of what a strong finish for this might be :).

Also, news fragment.

Done.

Please merge when these are addressed to your satisfaction.

Done.