The ST HAL should make programming STM32 microcontrollers easier. After all, it is a "Hardware Abstraction Layer". It provides an interface to the user, so he doesn't need to manipulate the hardware registers directly.
An abstraction layer is called "leaky" when its interface isn't sufficient, such that the user needs to dig deeper into the low-level stuff. The failure of an abstraction layer generally has two causes:
I didn't bumb into bugs in the ST HAL. It looks like the code is of good quality and well-maintained.
(2) Lacking documentation
This is definitely the weakest point of the ST HAL. The documentation is so brief that I end up doing this:
>> Study the whole (related) chapters in the "Reference Manual" of the chip
>> Open the functions of the ST HAL and read their code, study how the actual registers are manipulated
The lacking documentation forces the user to dig into the low-level stuff. This makes the abstraction very "leaky", up to the point that I start to question its benefits.
Dear STMicro - please consider more investments into the HAL docs.