Documentation: clarify that callback() may return before callback chain is complete

[jrennie]

This ticket simply requests that documentation for the callback and errback methods of twisted.internet.defer.Deferred clarify when they will return. As currently written, a programmer might assume that these methods will not return until the chain has completed. In fact, the methods will return as soon as they run into a Deferred-returning function in the chain. 'course, it's probably best to provide no guarantees as to when these functions will return in case the Twisted implementation changes.

[exarkun]

(In [29049]) Branching to 'callback-chaining-doc-4439'

[exarkun]

(In [29050]) Expand Deferred.callback docstring

refs #4439

[ivank]

Very minor nit: *error*- callback should be *error*-callback. Everything else looks good, please merge.

[exarkun]

(In [29113]) Merge callback-chaining-doc-4439

Author: exarkun Reviewer: ivank Fixes: #4439

Augment the Deferred.callback docstring with text about chaining.