Document errors via `@retval`

Besides existing `@return` doxygen tags for return types/objects, in some cases, we should enumerate possible values and errors with `@retval`.

Start by reviewing the existing C++ Doxygen comments that use @return tags and identify cases where possible values or errors are documented. Add @retval entries for those applicable cases, then verify that the affected documentation clearly enumerates the returned values and errors.

Written by the indexing model from the issue text.