gpio: fixup doxygen on `_dt` functions

Fixup the doxygen comments for return values on `_dt` functions.
@retval should only be used when specifying actual return values,
@return is more general and can refer to other functions.

Signed-off-by: Jordan Yates <jordan.yates@data61.csiro.au>