drivers: regulator: improve Doxygen documentation

- Remove redundant `@file`
- Hide driver-specific code using `INTERNAL_HIDDEN`.
- Use standard `@funcprops`
- Use `@retval` for return codes, and clarify them as well. Added -errno
  case, since external regulators may propagate e.g. bus errors.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>