device.h: clean up doxygen comments

The doxygen comments contain errors, grammar problems, and other
issues. Additionally, some internal macros have doxygen comments
instead of "plain" C comments. The docstrings also sometimes omit
important information.

Give the header a once-over to try to improve the situation.

Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>