Document middle
Add a note on return type in documentation of middle
Improve documentation of middle with suggestion of @pao
Merge pull request #8873 from remusao/master

Document middle (fix #8833)