drivers: pwm: improve error handling code and docs

Do not convert get_cycles_per_sec() failures to -EIO, just propagate the
failure code since the failure is not handled. As a consequence, all
Doxygen docstrings have been updated.

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