add documentation to the decorator
minor documentation corrections
chiiph's patch for rc2

* return deferred from addMessage
* convert StringIO types to string
* remove unneeded yields from the chain of deferreds in fetcher
fix tests after rewrite