Opened 9 years ago

Last modified 7 years ago

#5436 enhancement new

The documentation for Agent makes it kinda hard to figure out how to get through a whole request

Reported by: Glyph Owned by:
Priority: normal Milestone:
Component: web Keywords: documentation
Cc: jknight, sirkonst Branch:
Author:

Description

Walking through the new client with a user who had not touched it before, it was somewhat difficult to explain all the stuff you have to do in order to identify that the data from a server was fully received.

In the section on receiving responses in the new Agent documentation,

  1. The example is way too long; it should be easier to get the whole response. I think that some of the print lines can be compressed out in the interests of brevity.
  2. The text after the example says "It is important to inspect the Failure passed to connectionLost", but the example doesn't actually do that inspection. This is important because inspecting Failure objects is really not obvious, and isn't even an API link to Failure.
  3. There's no discussion of ResponseFailed, which seems like a more important case to describe (the server, being a good server, provided the mechanism to discover if the response actually got through to the client or not, and the client can authoritatively tell that it failed). It seems like this should really come first. (Why is _DataLoss a secret, if PotentialDataLoss isn't? Reading through _newclient.HTTPClientParser.connectionLost looked weird to me while I was looking at this.)
  4. The API reference doesn't mention this property of the request(...) method. You can chase down the IBodyProducer documentation to figure it out, but it might not be obvious that that's necessary; I think it would make sense for Agent to document the full lifecycle of the request issued by request itself, even if that's somewhat redundant.

Change History (3)

comment:1 Changed 9 years ago by DefaultCC Plugin

Cc: jknight added

comment:2 Changed 7 years ago by sirkonst

Cc: sirkonst added

ping

comment:3 Changed 7 years ago by Jean-Paul Calderone

sirkonst, adding "ping" to a ticket rarely does anything to help development progress. Please join the mailing list or the irc channel if you'd like to help out.

Note: See TracTickets for help on using tickets.