Documentation updates.

Made the Doxygen headers slightly clearer when directly read from the
header file, fixed grammar and spelling here and there, added some
missing \param and \return tags (though a lot remains to be done).