CC @nield apropos !2724, where I found myself having to write in the MR things that ought to be documented in-tree.
I'll assign review to @nickm since he is familiar with the background.