gpio: clean up API documentation
gpio: clean up API documentation

Use more standard Doxygen styling.  Add clarification to
recommendations and expectations.

Signed-off-by: Peter Bigot <a4112a160b558d5427af084318038e19a95979ee@nordicsemi.no>

zephyrproject-rtos/zephyr,finikorg/zephyr,zephyrproject-rtos/zephyr,finikorg/zephyr,zephyrproject-rtos/zephyr,galak/zephyr,galak/zephyr,nashif/zephyr,galak/zephyr,finikorg/zephyr,nashif/zephyr,zephyrproject-rtos/zephyr,galak/zephyr,Vudentz/zephyr,nashif/zephyr,finikorg/zephyr,nashif/zephyr,Vudentz/zephyr,Vudentz/zephyr,Vudentz/zephyr,Vudentz/zephyr,galak/zephyr,nashif/zephyr,Vudentz/zephyr,zephyrproject-rtos/zephyr,finikorg/zephyr