Ensure HAL is clearly specified

[ccollins476ad]

We should make sure the contract of each HAL function is clearly specified, both in header files and in the online documentation. The specification should aim to leave no questions unanswered for someone using the HAL or creating an implementation.

The specification indicate the defined behavior for particular conditions and argument values. When practical, instances of undefined behavior should be called out.

For example, for hal_flash_write():

• What gets returned when an invalid flash_id argument is specified? (-1)
• What happens when the specified region of flash is already written? (undefined)
• What happens when 0-byte write is performed? (no-op; 0 returned)

...and so on.

[sdalu]

One thing which is nicely done in ChibiOS documentation, is to have the driver state machine of each hal interface. For exemple: http://chibios.sourceforge.net/docs3/hal/group___i2_c.html

[sterlinghughes]

i agree, that is excellent. I will check chibios source, is there a doxygen format that allows you to build those state machines or is it embedding gifs?

[utzig]

https://www.graphviz.org/doc/info/lang.html