pwm: fix return types, more documentation and cleanup