Static Guarantees becomes Typestate Programming, as per @japaric 's suggestion

Author: jamesmunns

src/SUMMARY.md

@@ -24,10 +24,10 @@ more information and coordination
     - [The Borrow Checker](./peripherals/borrowck.md)
     - [Singletons](./peripherals/singletons.md)
     - [Peripherals in Rust](./peripherals/rusty.md)
-- [Static Guarantees](./static-guarantees/static-guarantees.md)
-    - [Strong Types](./static-guarantees/strong-types.md)
-    - [Design Contracts](./static-guarantees/design-contracts.md)
-    - [Zero Cost Abstractions](./static-guarantees/zero-cost-abstractions.md)
+- [Typestate Programming](./typestate-programming/typestate-programming.md)
+    - [Peripherals as State Machines](./typestate-programming/state-machines.md)
+    - [Design Contracts](./typestate-programming/design-contracts.md)
+    - [Zero Cost Abstractions](./typestate-programming/zero-cost-abstractions.md)
 - [Portability](./portability/portability.md)
     - [The Trait System](./portability/traits.md)
     <!-- TODO: Define more sections -->

src/static-guarantees/static-guarantees.md

@@ -1,5 +1,7 @@
 # Design Contracts
 
+In
+
 ```rust
 struct GpioPin; struct InputGpio; struct OutputGpio;
 

src/static-guarantees/strong-types.md

@@ -0,0 +1,5 @@
+# Peripherals as State Machines
+
+The peripherals of a microcontroller can be thought of as set of state machines. For example, a simplified [GPIO pin]
+
+[GPIO pin]: https://en.wikipedia.org/wiki/General-purpose_input/output

src/static-guarantees/design-contracts.md renamed to src/typestate-programming/design-contracts.md

@@ -0,0 +1,63 @@
+# Typestate Programming
+
+The concept of [typestates] describes the encoding of information about the current state of an object into the type of that object. Although this can sound a little arcane, if you have used the [Builder Pattern] in Rust, you have already started using Typestate Programming!
+
+[typestates]: https://en.wikipedia.org/wiki/Typestate_analysis
+[Builder Pattern]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html
+
+```rust
+#[derive(Debug)]
+struct Foo {
+    inner: u32,
+}
+
+struct FooBuilder {
+    a: u32,
+    b: u32,
+}
+
+impl FooBuilder {
+    pub fn new(starter: u32) -> Self {
+        Self {
+            a: starter,
+            b: starter,
+        }
+    }
+
+    pub fn double_a(self) -> Self {
+        Self {
+            a: self.a * 2,
+            b: self.b,
+        }
+    }
+
+    pub fn into_foo(self) -> Foo {
+        Foo {
+            inner: self.a + self.b,
+        }
+    }
+}
+
+fn main() {
+    let x = FooBuilder::new(10)
+        .double_a()
+        .into_foo();
+
+    println!("{:#?}", x);
+}
+```
+
+In this example, there is no direct way to create a `Foo` object. We must create a `FooBuilder`, and properly initialize it before we can obtain the `Foo` object we want.
+
+This minimal example encodes two states:
+
+* `FooBuilder`, which represents an "unconfigured", or "configuration in process" state
+* `Foo`, which represents a "configured", or "ready to use" state.
+
+## Strong Types
+
+Because Rust has a [Strong Type System], there is no easy way to magically create an instance of `Foo`, or to turn a `FooBuilder` into a `Foo` without calling the `into_foo()` method. Additionally, calling the `into_foo()` method consumes the original `FooBuilder` structure, meaning it can not be reused without the creation of a new instance.
+
+[Strong Type System]: https://en.wikipedia.org/wiki/Strong_and_weak_typing
+
+This allows us to represent the states of our system as types, and to include the necessary actions for state transitions into the methods that exchange one type for another. By creating a `FooBuilder`, and exchanging it for a `Foo` object, we have walked through the steps of a basic state machine.