Ticket #4478 task closed fixed

Opened 4 years ago

Last modified 3 years ago

Write a howto documenting endpoints

Reported by: itamar Owned by:
Priority: high Milestone:
Component: core Keywords: documentation
Cc: Branch: branches/endpoints-docs-4478-2
(diff, github, buildbot, log)
Author: exarkun, glyph Launchpad Bug:

Description

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

Change History

1

  Changed 4 years ago by exarkun

  • priority changed from normal to high

2

  Changed 4 years ago by glyph

  • milestone set to Twisted-10.1

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

3

  Changed 4 years ago by exarkun

  • owner changed from glyph to exarkun

4

  Changed 4 years ago by exarkun

  • branch set to branches/endpoints-docs-4478
  • branch_author set to exarkun

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

5

  Changed 4 years ago by 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

6

  Changed 4 years ago by jml

  • milestone Twisted-10.1 deleted

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.

7

  Changed 4 years ago by glyph

  • branch changed from branches/endpoints-docs-4478 to branches/endpoints-docs-4478-2
  • branch_author changed from exarkun to exarkun, glyph

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

8

  Changed 4 years ago by glyph

  • keywords documentation, review added; documentation removed
  • owner exarkun deleted

9

follow-up: ↓ 12   Changed 3 years ago by exarkun

  • owner set to glyph
  • keywords documentation added; documentation, review removed
  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.

10

  Changed 3 years ago by exarkun

Also, news fragment.

11

  Changed 3 years ago by glyph

  • status changed from new to closed
  • resolution set to fixed

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

12

in reply to: ↑ 9   Changed 3 years ago by 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.

13

  Changed 3 years ago by <automation>

  • owner glyph deleted
Note: See TracTickets for help on using tickets.