SPI: CS configuration "lockout", code, documentation, examples

[gnbl]

I'm using SPI3 (seems to be the default for SPI.begin() ) on a Nucleo-L432KC (STM32L432KC) like so

#include <SPI.h>
SPIClass io(D11, D12, D13);//, A3); // <- do not pass ssel or beginTransaction does not configure it

io.beginTransaction( A3, SPISettings(12e6, MSBFIRST, SPI_MODE0) );
io.transfer16(A3, 0xF0F1 );

because I prefer explicit configuration and later also want to use SPI1.

Configuration "lockout"
SPIClass must not instanciated with ssel or beginTransaction(uint8_t pin,... does not configure the CS pin.
Could this not also prevent using SPI interfaces other than default?

---

Edit: it probably was intended to be used like so ?

SPIClass io;
io.begin(A3); // -> SPI3 on STM32L432KC
io.beginTransaction( A3, SPISettings(12e6, MSBFIRST, SPI_MODE0) );

---

Code
Maybe it is also possible to simplify the keeping of the CS state? Variables, (private) members, parameters have very similar symbols (are they redundant?) and are even used mixed, which makes it a little hard to read IMO:

pin
ssel
_pin
_spi.pin_ssel
_CSpin

(magic) constants:

-1
0xFF
CS_PIN_CONTROLLED_BY_USER
NC

Documentation
Why are there almost no comments on what's happening (I know: "because I did not write them")? But seriously. Good code may not need comments, but no comments don't necessarily make good code..

Examples
It would be nice to have an example or an explanation on how to use different SPI peripherals. From what I understand, the CS pin determines the hardware peripheral!?

[ghost]

Hi @gnbl ,

Thank you for your feedback.
There is documentation in the wiki about the SPI API.

[fpistm]

Hi @gnbl , any feedback?

[ghost]

I reopened because we must increase the quality of comments in this code.