drivers: can: improve API documentation

Improve the CAN driver API documentation:
- Reorder API declarations and organize them into logical groups.
- Add doxygen strings where missing.
- Improve and unify wording of existing doxygen strings.
- Unify naming of callback function pointers as "callback".
- Unify naming of user-specified callback function arguments as
  "user_data".
- Instances and pointers to struct zcan_frame are named "frame",
  not "msg", to avoid confusion with the CAN message queue support.
- Check for __DOXYGEN__ to include documentation for optional APIs in
  the documentation.
- Use "@cond INTERNAL_HIDDEN" to hide internal API details such as padding.

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