Various changes to documentation in and outside the code. Most of them
are the result of a review by Emilio Cota and Samuel Iglesias (thanks!)
Signed-off-by: Alessandro Rubini <rubini@gnudd.com>