The Reference Manual is (in my opinion) the best documentation there is on how to use the peripherals that ST designed and built into their microcontrollers. (This is the primary reference but you sometimes also have to read the Programming Manual which describes the processor core and core peripherals designed by ARM).
These manuals are complicated for the simple reason that the microcontrollers are amazingly complicated - hence amazingly capable - devices.
In my opinion, HAL is not adequately documented. The documentation I have seen seems largely to be "doxygen" - namely what can be gleaned by looking at the appropriate header files, but formatted nicely. It tells you what the calls are, but not how (for example in what order) to use them.
For examples of how to use the HAL libraries, you have to look at the Stm32Cube firmware. But that does not give me an understanding of what's going on and why. For that, I find I have to look through the source-code of the HAL libraries, seeing what gets written and in what order. Where I'm having difficulty understanding the Reference Manual, this can help. But mostly I just look at the Reference Manual on its own; I only refer to HAL where my experiments are going nowhere.
But even that's not enough.
When you're dealing with (for example) I2C, this will tell you how to achieve a specific set of things happening on the I2C bus. But you have to look at the data-sheet of the external device (be it memory, I/O expander, accelerometer or whatever) to work out what things you need to tell the external device to get what you want to happen.
