drivers: pwm: clean up the PWM capture API documentation
drivers: pwm: clean up the PWM capture API documentation

Clean up the PWM capture API documentation a bit:
- Turn simple comments on PWM_CAPTURE_MODE_* into documentation comments
- Callback signature is always available, but note that PWM capture
  support is optional
- Remove double @a
- Document return codes from pwm_pin_{enable,disable}_capture()
- Change wording to reflect that pwm_pin_capture_*() returns a single
  result

Signed-off-by: Henrik Brix Andersen <24a3f13c22635bab658e39fc5f1e63c575328aae@vestas.com>

nashif/zephyr,nashif/zephyr,zephyrproject-rtos/zephyr,zephyrproject-rtos/zephyr,galak/zephyr,galak/zephyr,galak/zephyr,Vudentz/zephyr,zephyrproject-rtos/zephyr,Vudentz/zephyr,zephyrproject-rtos/zephyr,finikorg/zephyr,nashif/zephyr,zephyrproject-rtos/zephyr,nashif/zephyr,finikorg/zephyr,Vudentz/zephyr,Vudentz/zephyr,finikorg/zephyr,finikorg/zephyr,nashif/zephyr,finikorg/zephyr,Vudentz/zephyr,galak/zephyr,Vudentz/zephyr,galak/zephyr