doc: Edit the SPI driver APIs

Edit public API details for clarity, grammar, punctuation found
on file spi.h

Made consistent use of @retval to document return values.

Used imperative verbs for all @brief descriptions.

Change-Id: Ie53eeeb79d399e8474fe7341a396f5437c2999dc
Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>