wiki:DocumentationAnalysis/Clients/AndrewBennetts

Review Details

Document Expectations

Intended User

Before someone begins using this document, I'd really really like it if they knew:

  • more or less what a TCP socket is, and that they connect to endpoints specified by host + port.
  • more or less what Deferreds are.

Once someone has read this document they should understand:

  • how to write a Twisted program that connects (and uses) a single TCP client.
  • how to write a Twisted program that connects & uses multiple concurrent TCP clients.
  • how to write a Twisted program that uses TCP clients concurrently with other functionality, like running a TCP server.
  • how to use ClientCreator to create try-once client connection.
  • how to use ReconnectingClientFactory to make a client that tries to reconnect lost connections automatically.
  • how to define custom reconnection logic (in the same manner that ReconnectingClientFactory does), including how to abort a connection attempt.
  • that Protocols work the same way for servers and clients (even though most protocols aren't symmetrical).

Document Review

Coverage of subject matter

This document seems to cover the following subject matter at least acceptably well:

  • the relationship of protocol instances to connections (although theoretically this doesn't have to be true, in practice most ClientFactories do this, so the simplification here is fine).
  • it recommends the use of ReconnectingClientFactory for reconnection logic, and gives an example of using it.
  • the ircLogBot example is a good, real example, that does something useful and interesting, and demonstrates use of ClientFactory and reactor.connectTCP. (and judging from the number of times I've seen "twistedbot" join #twisted, people actually run and play with this code a fair bit).

This document seems to be attempting to cover the following subject matter, but its coverage is flawed:

  • the use of the term "configuration" for application state usually held in a factory is confusing and probably too abstract.
  • the example in "Simple, single-use clients" is good, except that it's not quite a complete, executable example. It should have a reactor.run() line.
  • "Simple, single-use clients" should give a comprehensive list of methods that are specific to ClientFactories (or perhaps this could come later in the document, but it definitely should be in this document somewhere).
  • "Simple, single-use clients" gives an example that needs to take connector arguments, and although it never uses them, it's a bit weird to just never mention them or what they are here. Also, it should say that "reason" is a Failure; basically, ClientFactory should be introduced with a comprehensive API overview.
  • The "To connect this EchoClientFactory to a server, you could use this code:" snippet may as well be part of the main example in this section.
  • The "Reconnection" section starts talking about calling various methods on the "connector" variable, but never says what it is or links to the API docs for IConnector.
  • The explanation of ClientCreator is too terse -- e.g. it doesn't make it clear that it returns a Deferred of the connected protocol.
  • The ircLogBot example imports twisted.protocols.irc, which has been deprecated. It should import twisted.words.protocols.irc instead.

This document ought to be covering the following subject matter but is not:

  • Never are connectors or the IConnector interface explained.
  • The APIs of ClientFactory, IConnector, Protocol, ClientCreator.
  • How to make concurrent connections -- it should explicitly state that:
    • connectTCP (and other variations like ClientCreator, connector.connect()) don't block -- they start the process of establishing the connection, and you wait for an event handler like connectionMade to be called.
    • you can simply call connectTCP (or whatever) multiple times -- in a row, even -- to make multiple connections. It's obvious once you "get it", but needs to be explicitly stated, as it's not obvious to many people new to Twisted.

This document could be supplemented by links to these existing follow-up ("now that you know X you can try Y") documents:

  • GUI docs (because client programs are often interactive)
    • Choosing a reactor and GUI toolkit integration
    • examples: qtdemo.py, pyuidemo.py, wxdemo.py
  • stdindemo.py (again, interactivity)
  • Reactor basics
  • Logging howto

This document could be supplemented by as-yet non-existant pre-requisite ("you should read this first") documents on:

  • "Mastering TCP in under 3 minutes" ;)

This document could be supplemented by links to these as-yet non-existant follow-up ("now that you know X you can try Y") documents:

  • comprehensive description of twisted.internet.protocol.Protocol, the methods you can override, and the actions you can perfrom (e.g. self.transport.loseConnection()). i.e. "Guide to writing protocols"
  • Guide to twisted.protocols.basic
  • Guide to twisted.words.protocols.irc (for better understanding of the IRC example).
  • Guide to twisted.internet.stdio (many client programs are likely to be interactive).
  • gtkdemo.py (we seem to have one for every other GUI...)

Style

The following changes to the style of the document would make it easier to read:

  • typo: s/decended/descended/
  • it starts with a pretty jargon-heavy introduction. I think a simple example that is then dissected would be a better introduction.
  • "is usually where set up" -> "is where set up usually"
  • s/protocl/protocol/
  • first sentence of ClientFactory is "We use reactor.connect* and a ClientFactory." The sentence doesn't really make sense... use it to do what? I'd expect some sort of explanation about why you'd want to use it, e.g. "ClientFactory can be subclassed to XXX."
  • "Persistent Data in the Factory" appears to be presenting an extract of the previous example (to highlight certain things), but it's not clear that this is an extract rather than a new example.

Overall summary

This document is: better than having no documentation, but with some glaringly obvious improvements to make

Last modified 8 years ago Last modified on 03/06/2006 07:19:01 AM