diff --git a/api/src/commonMain/kotlin/Endpoint.kt b/api/src/commonMain/kotlin/Endpoint.kt
index 7e34ee0..de72bc1 100644
--- a/api/src/commonMain/kotlin/Endpoint.kt
+++ b/api/src/commonMain/kotlin/Endpoint.kt
@@ -99,6 +99,11 @@ import kotlin.reflect.KProperty
  * Note, however, that this guarantees that your code will stop compiling in future versions of this library.
  */
 sealed interface AnyEndpoint {
+	/**
+	 * The [Resource] this [Endpoint][AnyEndpoint] is declared as a part of.
+	 *
+	 * For example, `GET /api/v2/users` is an endpoint of the resource `/api/v2/users`.
+	 */
 	val resource: Resource
 
 	/**
@@ -109,7 +114,21 @@ sealed interface AnyEndpoint {
 	/**
 	 * Optional path extension from the [Resource] this endpoint is a part of.
 	 *
-	 * To access the real path of this endpoint, see [ResolvedEndpoint.path].
+	 * For example, the endpoint:
+	 * ```kotlin
+	 * object Users : RootResource("/users") {
+	 *     val list by get()
+	 * }
+	 * ```
+	 * has a [path] of `null`, but the endpoint:
+	 * ```kotlin
+	 * object Users : RootResource("/users") {
+	 *    val me by get("/me")
+	 * }
+	 * ```
+	 * has a [path] of `"/me"`.
+	 *
+	 * To access the full path of this endpoint, resolve it (see [ResolvedResource]) then access [ResolvedEndpoint.path].
 	 */
 	val path: Path.Segment?
 
@@ -126,6 +145,8 @@ sealed interface AnyEndpoint {
 	/**
 	 * Constructor for query parameters.
 	 *
+	 * This field contains a function that creates a [Parameters] instance from some [ParameterStorage].
+	 *
 	 * If no query parameters are used by this endpoint, this function returns [Parameters.Empty].
 	 */
 	val buildParameters: ParameterConstructor<Parameters>
diff --git a/api/src/commonMain/kotlin/Failure.kt b/api/src/commonMain/kotlin/Failure.kt
index 6f129df..701f421 100644
--- a/api/src/commonMain/kotlin/Failure.kt
+++ b/api/src/commonMain/kotlin/Failure.kt
@@ -92,9 +92,35 @@ sealed interface FailureSpec {
 	 *
 	 * This type is used to type-safely represent an endpoint that can failure in multiple different ways.
 	 * It is not expected that end-users need to use this type, though you may see it appear in inlay hints.
+	 *
+	 * ### Union types
+	 *
+	 * This type emulates a union of two types.
+	 * It can be expanded into a union of arbitrary arity by using [Or] recursively.
+	 * By convention, [Or] instances can only appear in [A], not in [B].
+	 *
+	 * By convention, [Or] unions always start with the [Never] type.
+	 *
+	 * Therefore, [a] can contain either [Never] or [Or]. [b] can contain only proper failure types, like [ByCode].
+	 * The following union follows these rules:
+	 * ```kotlin
+	 * val a = Or(Never, Or(ByCode(502), Or(ByCode(404), ByCode(403))))
+	 * ```
 	 */
 	class Or<out A : FailureSpec, out B : FailureSpec>(
+		/**
+		 * The left-hand side of the union.
+		 *
+		 * By convention, this field can only contain [Never] or [Or] instances.
+		 * If this convention is not respected, the union may not be properly recognized by the library methods.
+		 */
 		val a: A,
+		/**
+		 * The right-hand side of the union.
+		 *
+		 * By convention, this field can only contain proper failure specifications, like [ByCode].
+		 * If this convention is not respected, the union may not be properly recognized by the library methods.
+		 */
 		val b: B,
 	) : FailureSpec
 }
@@ -126,7 +152,7 @@ private fun FailureSpec.all(): Sequence<FailureSpec> = sequence {
  *    companion object : FailureCompanion<UserNotFound>(HttpStatusCode.NotFound)
  * }
  *
- * // …An endpoint in a resources…
+ * // …An endpoint in a resource…
  * val getMe by get("me")
  *     .result<UserDto>()
  *     .failure(UserNotFound)
diff --git a/api/src/commonMain/kotlin/ResolvedResource.kt b/api/src/commonMain/kotlin/ResolvedResource.kt
index 4877859..e820552 100644
--- a/api/src/commonMain/kotlin/ResolvedResource.kt
+++ b/api/src/commonMain/kotlin/ResolvedResource.kt
@@ -4,8 +4,9 @@ package opensavvy.spine.api
  * A resolved [Resource].
  *
  * The [Resource] class represents the _declaration_ of a resource.
- * For example, the `/api/users/{user}` is not a 'real' resource.
- * This class, [ResolvedResource], represents 'real' resources: '/api/users/111' and '/api/users/222' are possible
+ * For example, the `/api/users/{user}` is not a 'real' resource: it is a pattern
+ * from which multiple resources can be created (each user gets their own resource).
+ * This class, [ResolvedResource], represents 'real' resources: `/api/users/111` and `/api/users/222` are possible
  * values of this class.
  *
  * To instantiate this class, specify the full path from the root, adding necessary runtime information where necessary.