include: spi.h: Fix documentation oddities

The recent change to spi.h doc merged a bit too early on accident and
some oddities were left over, fix them, including:

- Weird command causing strange broken topics section in output
- spi_iodev_api should probably be hidden, looks strange in its own
  section on the doc output
- Fix return values of transceive based functions to match transceive
  description

Signed-off-by: Declan Snyder <declan.snyder@nxp.com>