Merge #294

294: Add project scope to readme + document fallibility r=ryankurte a=eldruin

This replaces #293 
Closes #293

Co-authored-by: Diego Barrios Romero <[email protected]>

Author: bors[bot]

README.md

@@ -13,6 +13,27 @@ This project is developed and maintained by the [HAL team][team].
 
 [API reference]: https://docs.rs/embedded-hal
 
+## Scope
+
+`embedded-hal` serves as a foundation for building an ecosystem of platform agnostic drivers.
+(driver meaning library crates that let a target platform interface an external device like a digital
+sensor or a wireless transceiver).
+
+The advantage of this system is that by writing the driver as a generic library on top
+of `embedded-hal` driver authors can support any number of target
+platforms (e.g. Cortex-M microcontrollers, AVR microcontrollers, embedded Linux, etc.).
+
+The advantage for application developers is that by adopting `embedded-hal` they can unlock all
+these drivers for their platform.
+
+`embedded-hal` is not tied to a specific execution model like blocking or non-blocking.
+
+For functionality that goes beyond what is provided by `embedded-hal`, users are encouraged
+to use the target platform directly. Abstractions of common functionality can be proposed to be
+included into `embedded-hal` as described [below](#how-to-add-a-new-trait), though.
+
+See more about the design goals in [this documentation section](https://docs.rs/embedded-hal/latest/embedded_hal/#design-goals).
+
 ## Releases
 
 At the moment we are working towards a `1.0.0` release (see [#177]). During this process we will

src/lib.rs

@@ -34,6 +34,11 @@
 //! advantage for application developers is that by adopting `embedded-hal` they can unlock all
 //! these drivers for their platform.
 //!
+//! - Trait methods must be fallible so that they can be used in any possible situation.
+//! Nevertheless, HAL implementations can additionally provide infallible versions of the same methods
+//! if they can never fail in their platform. This way, generic code can use the fallible abstractions
+//! provided here but platform-specific code can avoid fallibility-related boilerplate if possible.
+//!
 //! # Out of scope
 //!
 //! - Initialization and configuration stuff like "ensure this serial interface and that SPI