update docs to mention durability

book/src/SUMMARY.md

@@ -16,6 +16,7 @@
   - [Defining the checker](./tutorial/checker.md)
   - [Defining the interpreter](./tutorial/interpreter.md)
 - [Reference](./reference.md)
+  - [Durability](./reference/durability.md)
   - [Algorithm](./reference/algorithm.md)
 - [Common patterns](./common_patterns.md)
   - [Selection](./common_patterns/selection.md)

book/src/overview.md

@@ -114,9 +114,12 @@ Finally, you can also modify the value of an input field by using the setter met
 Since this is modifying the input, the setter takes an `&mut`-reference to the database:
 
 ```rust
-file.set_contents(&mut db, String::from("fn foo() { /* add a comment */ }"));
+file.set_contents(&mut db).to(String::from("fn foo() { /* add a comment */ }"));
 ```
 
+Note that the setter method `set_contents` returns a "builder".
+This gives the ability to set the [durability](./reference/durability.md) and other advanced concepts.
+
 ## Tracked functions
 
 Once you've defined your inputs, the next thing to define are **tracked functions**:
@@ -147,12 +150,13 @@ Tracked functions can return any clone-able type. A clone is required since, whe
 
 **Tracked structs** are intermediate structs created during your computation.
 Like inputs, their fields are stored inside the database, and the struct itself just wraps an id.
-Unlike inputs, they can only be created inside a tracked function, and their fields can never change once they are created.
-Getter methods are provided to read the fields, but there are no setter methods[^specify]. Example:
+Unlike inputs, they can only be created inside a tracked function, and their fields can never change once they are created (until the next revision, at least).
+Getter methods are provided to read the fields, but there are no setter methods. 
+Example:
 
 ```rust
 #[salsa::tracked]
-struct Ast {
+struct Ast<'db> {
     #[return_ref]
     top_level_items: Vec<Item>,
 }

book/src/reference/durability.md

@@ -0,0 +1,13 @@
+# Durability
+
+"Durability" is an optimization that can greatly improve the performance of your salsa programs.
+Durability specifies the probably that an input's value will change.
+The default is "low durability".
+But when you set the value of an input, you can manually specify a higher durability,
+typically `Durability::HIGH`.
+Salsa tracks when tracked functions only consume values of high durability
+and, if no high durability input has changed, it can skip traversing their
+dependencies.
+
+Typically "high durability" values are things like data read from the standard library
+or other inputs that aren't actively being edited by the end user.