Document clock type design in more detail

[Rahix]

From #443.

Right now, the clock types are used across the HAL, but there is no real documentation anywhere which explains how these clock types are intended to be used. We should give more examples on how this works and especially also document how one could migrate from the "hidden" clock API of arduino-hal to the explicit clock API of e.g. atmega-hal.

[Rahix]

Improved documentation in commit 75820c5 ("generic: Improve documentation of clock module").

Still need to document how migration from arduino-hal to atmega-hal would work.