drivers/periph/spi: clean up error codes and doc
drivers/periph/spi: clean up error codes and doc

- Use negative errno as error codes, rather than home-grown enums
    - Update the home-grown enum with negative errno codes for backward
      compatibility and mark it deprecated
- Update API doc to use negative errno codes
- Fix various style issues in Doxygen doc
    - Use `@retval` to document specific return values instead of abusing
      `@return` for this
    - Align parameters to proper indent level

RIOT-OS/RIOT,kYc0o/RIOT,miri64/RIOT,OTAkeys/RIOT,OTAkeys/RIOT,ant9000/RIOT,RIOT-OS/RIOT,ant9000/RIOT,kaspar030/RIOT,miri64/RIOT,miri64/RIOT,RIOT-OS/RIOT,jasonatran/RIOT,authmillenon/RIOT,ant9000/RIOT,OlegHahm/RIOT,jasonatran/RIOT,authmillenon/RIOT,authmillenon/RIOT,jasonatran/RIOT,kYc0o/RIOT,kaspar030/RIOT,OlegHahm/RIOT,RIOT-OS/RIOT,OTAkeys/RIOT,OlegHahm/RIOT,kYc0o/RIOT,ant9000/RIOT,kaspar030/RIOT,OTAkeys/RIOT,OlegHahm/RIOT,miri64/RIOT,authmillenon/RIOT,kYc0o/RIOT,RIOT-OS/RIOT,kaspar030/RIOT,kYc0o/RIOT,authmillenon/RIOT,ant9000/RIOT,kaspar030/RIOT,OlegHahm/RIOT,miri64/RIOT,jasonatran/RIOT,OTAkeys/RIOT,jasonatran/RIOT,authmillenon/RIOT