Ensure HAL is clearly specified

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.

Start by reviewing the HAL header files and corresponding online documentation, then use hal_flash_write() as the concrete example. Document each HAL function's behavior for relevant conditions and argument values, including return values and undefined behavior where practical. Done means the contracts are clear in both the headers and online documentation.

Written by the indexing model from the issue text.