All the documentation I could find is in docs/deferred.txt. Let me paste the paragraph:
"A few of the database updates required by various functions here can be deferred until after the result page is displayed to the user. For example, updating the view counts, updating the linked-to tables after a save, etc. PHP does not yet have any way to tell the server to actually return and disconnect while still running these updates (as a Java servelet could), but it might have such a feature in the future."
That text has been there at least since 2005. Given that to my knowledge there still is no such feature: I've spent hours trying to investigate why DeferrableUpdates delayed the page delivery as I incorrectly assumed those would be run after page has been delivered and trying to figure out if it is possible to make them actually work that way with PHP-FPM and nginx.
Should we just get rid of them? That should be easy, by either moving stuff to the jobqueue or just executing the code immediately.
Or if they are useful for something, can we at least document the *class* to reflect how it actually works and what it is useful for?
-Niklas