`@return` is dedicated for brief description of return values, not for comments
stating actual return values. In addition, sphinx + breathe does not join
multiple adjacent `@return`. This results in multiple `Return` sections in the
generated document, which is confusing.
This patch replaces `@return` with `@retval` for the lists of return
values. Adjacent `@retval` can be joined into one list by breathe.
v1 -> v2:
* Replace return value descriptions like `negative` and `positive` with
expressions like `<0` and `>0` in `@retval`.
* Keep the list of `@retval` comprehensive, even when there is a `@return` to
generally describe what the return value means.
* Drop duplicated `@return` when it does not give more information than the
`@retval` list.
Tracked-On: #1595
Signed-off-by: Junjie Mao <junjie.mao@intel.com>
584f6b7255