Clarify what the Requestcontext is for

Author: Joannis

Sources/Hummingbird/Server/RequestContext.swift

@@ -54,8 +54,18 @@ public struct CoreRequestContextStorage: Sendable {
     }
 }
 
-/// Protocol that all request contexts should conform to. Holds data associated with
-/// a request. Provides context for request processing
+/// Protocol that all request contexts should conform to. A RequestContext is a statically typed metadata container for information
+/// that is associated with a ``Request``, and is therefore instantiated alongside the request.
+///
+/// It's passed along the whole middleware chain through to the route. This allows middleware and the route to share this metadata.
+///
+/// Typical use of a context includes:
+/// - The origin that sent the request (IP address or otherwise)
+/// - The identity, such as a user, that is associated with this request
+///
+/// The context is a statically typed metadata container for the duration of a single request. It's used to store values between middleware and routes such as the user's identity.
+///
+/// The lifetime of a RequestContext should not exceed that of the request.
 public protocol RequestContext: InitializableFromSource, RequestContextSource {
     associatedtype Source: RequestContextSource = ApplicationRequestContextSource
     associatedtype Decoder: RequestDecoder = JSONDecoder