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 <hebad@vestas.com>