Document middle (fix #8833)

This an attempt to fix #8833 issue by documenting `middle`. It's my first pull request, so I hope it's ok.

Rémi

It might be useful to mention that `middle(x)` and `middle(x, x)` always return the same type -- one of the motivation of introducing the `middle` function is to ensure the type-stability of `median`.