drivers/periph/timer: documentation and code style improvements

[crasbe]

Contribution description

Just the usual stuff. The only noteworthy addition is the information that TIM_FLAG_RESET_ON_MATCH and TIM_FLAG_RESET_ON_SET reset the counter to zero. That was unclear which is why I looked at the code and decided to add this piece of information.

Also, since the RP2350 timer implementation uses ERRNO return values, I adapted the return value information for the timer functions and added a note that some functions can, but not necessarily will return ERRNOs on error.

Testing procedure

Look at the docs 👀

Issues/PRs references

Noticed while reviewing #22375.

Declaration of AI-Tools / LLMs usage:

AI-Tools / LLMs that were used are:

• none

[riot-ci]

Murdock results

✔️ PASSED

fde0e14 drivers/periph/timer: documentation and code style improvements

Success	Failures	Total	Runtime
11123	0	11124	10m:39s

Artifacts

• Documentation preview

[kfessel]

👍