spi: Cleanup and fix SPI docs build

Use the defined(__DOXYGEN__) more specifically in the header to better
match i2c.h and make things more explicit. Removes the define being
setup in zephyr.doxyfile.in.

Fixes some of the deprecation notes and what to look for instead. Fixes
some typos.

The async, signal, and rtio APIs for SPI are now shown in the built docs
as would be expected.

Signed-off-by: Tom Burdick <thomas.burdick@intel.com>