doc: replace return with retval

`@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>

hypervisor/include/common/irq.h

@@ -50,8 +50,8 @@ struct irq_desc {
  *			IRQF_LEVEL - 1: level trigger; 0: edge trigger;
  *    			IRQF_PT    - 1: for passthrough dev
  *
- * @return valid irq num - on success
- * @return IRQ_INVALID - on failure
+ * @retval >=0 on success
+ * @retval IRQ_INVALID on failure
  */
 int32_t request_irq(uint32_t req_irq, irq_action_t action_fn, void *priv_data,
 			uint32_t flags);