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

[zooko]

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

[exarkun]

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

[glyph]

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!

[exarkun]

(In [36452]) Some more links

refs #6194

[exarkun]

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