Opened 5 years ago

Closed 5 years ago

#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: Jean-Paul Calderone
Priority: low Milestone:
Component: core Keywords: docs
Cc: Branch: branches/callback-docs-6194
branch-diff, diff-cov, branch-cov, buildbot
Author: exarkun


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():

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

Such documentation probably belongs here:

Change History (5)

comment:1 Changed 5 years ago by Jean-Paul Calderone

Author: exarkun
Branch: branches/callback-docs-6194

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

comment:2 Changed 5 years ago by Jean-Paul Calderone

Keywords: review added

comment:3 Changed 5 years ago by Glyph

Keywords: review removed
Owner: set to Jean-Paul Calderone

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?)


comment:4 Changed 5 years ago by Jean-Paul Calderone

(In [36452]) Some more links

refs #6194

comment:5 Changed 5 years ago by Jean-Paul Calderone

Resolution: fixed
Status: newclosed

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