id,summary,reporter,owner,description,type,status,priority,milestone,component,resolution,keywords,cc,branch,branch_author,launchpad_bug
5775,Documentation for defer.gatherDeferreds and defer.DeferredList is not clear,cyli,,"[http://twistedmatrix.com/documents/current/api/twisted.internet.defer.DeferredList.html The documentation for DeferredList] makes mention of the DeferredList changing what callbacks/errbacks on the individual Deferreds can see, an elaboration as to why would be helpful.

The `consumeErrors` parameter's description is also confusingly worded, with alternating usage of the terms ""included Deferreds"" and ""individual Deferreds"".  Some examples (or given the different parameters `DeferredList` takes, perhaps a table) would help readers understand the behaviour better.

[http://twistedmatrix.com/documents/current/api/twisted.internet.defer.html#gatherResults The documentation for gatherResults] has the same confusing wording.  In addition, it does not mention that `gatherResults` is implemented with `DeferredList` with `fireOnFirstError` set to True, and thus that the `Failure` that is returned will be a `FirstError`.",defect,new,normal,,core,,documentation,,,,