#6194 enhancement closed fixed (fixed)

the doc of Deferred.callback() doesn't tell me what will happen if the deferred has already been triggered

Reported by: zooko Owned by: exarkun
Priority: low Milestone:
Component: core Keywords: docs
Cc: Branch: branches/callback-docs-6194
(diff, github, buildbot, log)
Author: exarkun Launchpad Bug:

Description

A colleague (David-Sarah), is proposing to add code to Tahoe-LAFS in order to work-around some unspecified limitations or problems in how Deferred handles repeated callback():

https://github.com/davidsarah/tahoe-lafs/commit/0350abb182f1fb6e4297f3c5942909a5498f5ba2#L1R46

I'd like to read some documentation about how Deferred does, or is supposed to, handle that.

Such documentation probably belongs here: http://twistedmatrix.com/documents/current/api/twisted.internet.defer.Deferred.html#callback

Change History (5)

comment:1 Changed 21 months ago by exarkun

  • Author set to exarkun
  • Branch set to branches/callback-docs-6194

(In [36449]) Branching to 'callback-docs-6194'

comment:2 Changed 21 months ago by exarkun

  • Keywords review added

comment:3 Changed 21 months ago by glyph

  • Keywords review removed
  • Owner set to exarkun

Looks like a great addition to the docs, please land.

Two minor notes which you may wish to address as well:

  1. "The object to supply as the result of this L{Deferred}." is obviously an improvement over what was there previously (by which I mean, of course, "nothing") but it is somewhat generally phrased. I think a lot of redundancy and inter-linking of documentation is useful in this area. For example, "the object which will be passed to the first callback added to this L{Deferred} with C{addCallback}". Explaining what each method does in terms of other methods is useful for someone who has a general idea of what is going on but is trying to piece it together by looking at reference documentation.
  2. L{} is superior to C{} if it can be made to work, since it linkifies things within the documentation and is therefore richer and more precise. I would suggest that you might want to do something like L{callback <Deferred.callback>} rather than C{callback}. (Maybe pydoctor should be modified so just L{callback} would work in that case, if it doesn't already?)

Thanks!

comment:4 Changed 21 months ago by exarkun

(In [36452]) Some more links

refs #6194

comment:5 Changed 21 months ago by exarkun

  • Resolution set to fixed
  • Status changed from new to closed

(In [36453]) Merge callback-docs-6194

Author: exarkun
Reviewer: glyph
Fixes: #6194

Expand the API documentation for Deferred.callback and Deferred.errback, in
particular describing what happens if these methods are called more than once on
a single Deferred.

Note: See TracTickets for help on using tickets.