Add a dedicated chapter for generic lifetimes

This is only a bare-bones skeleton. The intent is that this should get
filled out with more rules specific to generic lifetimes.

Author: ehuss

book.toml

@@ -51,6 +51,7 @@ use-boolean-and = true
 "/glossary.html#object-safe-traits" = "glossary.html#dyn-compatible-traits"
 "/items/extern-crates.html#extern-prelude" = "../names/preludes.html#extern-prelude"
 "/items/generics.html" = "../types/generics/index.html"
+"/items/generics.html#generic-lifetimes" = "../types/generics/lifetimes.html"
 "/items/generics.html#where-clauses" = "../trait-bounds.html#where-clauses"
 "/items/modules.html#prelude-items" = "../names/preludes.html"
 "/items/traits.html#object-safety" = "traits.html#dyn-compatibility"

src/SUMMARY.md

@@ -93,6 +93,7 @@
         - [Type parameters](types/parameters.md)
         - [Inferred type](types/inferred.md)
     - [Generics](types/generics/index.md)
+        - [Generic lifetimes](types/generics/lifetimes.md)
         - [Generic constants](types/generics/constants.md)
     - [Dynamically sized types](dynamically-sized-types.md)
     - [Type layout](type-layout.md)

src/types/generics/index.md

@@ -2,7 +2,7 @@ r[generics]
 # Generics
 
 r[generics.intro]
-Generics allow items to be parameterized by types, lifetimes, and [constants]. This allows definitions to be written in a flexible way that can be reused with different concrete types and values.
+Generics allow items to be parameterized by types, [lifetimes], and [constants]. This allows definitions to be written in a flexible way that can be reused with different concrete types and values.
 
 r[generics.parameters]
 ## Generic parameters
@@ -352,6 +352,7 @@ The [built-in attributes] that have meaning on a generic parameter are [`cfg`] a
 [implementations]: items.impl
 [item declarations]: statement.item
 [lifetime elision]: lifetime-elision
+[lifetimes]: generics.lifetimes
 [paths in expressions]: paths.expr
 [paths in types]: paths.type
 [qualified path]: paths.qualified

src/types/generics/lifetimes.md

@@ -0,0 +1,28 @@
+r[generics.lifetimes]
+# Generic lifetimes
+
+r[generics.lifetimes.intro]
+A *lifetime parameter* is a generic parameter for a lifetime.
+
+r[generics.lifetimes.at-least-once]
+[Structs], [enumerations], and [unions] must use each of their lifetime parameters at least once in their fields or variants.
+
+> [!EXAMPLE]
+> ```rust,compile_fail
+> // ERROR: lifetime parameter `'a` is never used
+> struct Foo<'a>;
+>
+> // ERROR: lifetime parameter `'a` is never used
+> enum Bar<'a> { A }
+> ```
+>
+> ```rust
+> // OK: `'a` appears in a field.
+> struct Ref<'a, T> {
+>     r: &'a T,
+> }
+> ```
+
+[enumerations]: items.enum
+[structs]: items.struct
+[unions]: items.union