kern_reboot(9): describe event handlers

Add more details about the execution and purpose of these shutdown
handlers. Make a point to mention the requirement that they can be run
in a normal or panic context. Add some simple examples.

Add a brief comment to the declaration in sys/eventhandler.h.

Reviewed by: markj
Discussed with: rpokala, Pau Amma <pauamma@gundo.com>
MFC after: 1 week
Sponsored by: The FreeBSD Foundation
Differential Revision: https://reviews.freebsd.org/D39135