From 5b368602fe47d6edf18f116244c2c039ace2f2ff Mon Sep 17 00:00:00 2001
From: Louis Seubert <louis.seubert.ls@gmail.com>
Date: Sun, 12 Jul 2026 18:35:50 +0200
Subject: [PATCH] docs(result): document that failure equality ignores error
 content

Result/Result<T> equality treats any two failures as equal regardless of their
Error, which was undocumented and surprising for failure-specific branching.
---
 CHANGELOG.md                                  |  2 ++
 .../ResultEqualityTests.cs                    | 20 +++++++++++++++++++
 src/request.result/Result.Equality.cs         | 20 ++++++++++++++++---
 3 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a7f9bdb..006fd7b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -45,6 +45,8 @@ To have a consistent experience across all packages, some public interfaces have
 
 ### Changed
 
+- **request.result:** Document that `Result`/`Result<T>` equality treats any two failures as equal, ignoring error content; branch on the `Error` directly for failure-specific logic
+
 ### Fixed
 
 - **request.result:** Correct the namespace in the `Prelude` doc comment (`Geekeey.Extensions.Result` → `Geekeey.Request.Result`)
diff --git a/src/request.result.tests/ResultEqualityTests.cs b/src/request.result.tests/ResultEqualityTests.cs
index ad54683..99d7094 100644
--- a/src/request.result.tests/ResultEqualityTests.cs
+++ b/src/request.result.tests/ResultEqualityTests.cs
@@ -190,6 +190,26 @@ internal sealed class ResultEqualityTests
 		await Assert.That(success.GetHashCode()).IsNotEqualTo(failure.GetHashCode());
 	}
 
+	[Test]
+	public async Task I_can_equal_failure_and_failure_ignoring_error_content()
+	{
+		var a = Prelude.Failure<int>("error 1");
+		var b = Prelude.Failure<int>("error 2");
+
+		await Assert.That(a.Equals(b)).IsTrue();
+		await Assert.That(a.Error).IsNotEqualTo(b.Error);
+	}
+
+	[Test]
+	public async Task I_can_equal_non_generic_failure_and_failure_ignoring_error_content()
+	{
+		var a = Prelude.Failure("error 1");
+		var b = Prelude.Failure("error 2");
+
+		await Assert.That(a.Equals(b)).IsTrue();
+		await Assert.That(a.Error).IsNotEqualTo(b.Error);
+	}
+
 	[Test]
 	public async Task I_can_equal_non_generic_result_and_get_true_for_success_and_success()
 	{
diff --git a/src/request.result/Result.Equality.cs b/src/request.result/Result.Equality.cs
index 2a8cbbb..da9372d 100644
--- a/src/request.result/Result.Equality.cs
+++ b/src/request.result/Result.Equality.cs
@@ -9,7 +9,15 @@ namespace Geekeey.Request.Result;
 
 public partial class Result : IEquatable<Result>
 {
-	/// <inheritdoc/>
+	/// <summary>
+	/// Checks whether two results are equal. Results are equal if both are success or both are failure.
+	/// </summary>
+	/// <remarks>
+	/// Two failures are considered equal regardless of their <see cref="Error"/> content. Equality therefore
+	/// ignores the error; if you need to branch on a specific failure, compare the <see cref="Error"/> values
+	/// directly instead of relying on equality.
+	/// </remarks>
+	/// <param name="other">The result to check for equality with the current result.</param>
 	[Pure]
 	public bool Equals(Result? other)
 	{
@@ -49,7 +57,8 @@ public partial class Result : IEquatable<Result>
 public partial class Result : IEqualityOperators<Result, Result, bool>
 {
 	/// <summary>
-	/// Checks whether two results are equal. Results are equal if they are both success or both failure.
+	/// Checks whether two results are equal. Results are equal if they are both success or both failure. Two
+	/// failures are equal regardless of their error content.
 	/// </summary>
 	/// <param name="a">The first result to compare.</param>
 	/// <param name="b">The second result to compare.</param>
@@ -79,6 +88,11 @@ public partial class Result<T> : IEquatable<Result<T>>, IEquatable<T>
 	/// Checks whether the result is equal to another result. Results are equal if both results are success values and
 	/// the success values are equal, or if both results are failures.
 	/// </summary>
+	/// <remarks>
+	/// Two failures are considered equal regardless of their <see cref="Error"/> content. Equality therefore
+	/// ignores the error; if you need to branch on a specific failure, compare the <see cref="Error"/> values
+	/// directly instead of relying on equality.
+	/// </remarks>
 	/// <param name="other">The result to check for equality with the current result.</param>
 	[Pure]
 	public bool Equals(Result<T>? other)
@@ -194,7 +208,7 @@ public partial class Result<T> : IEqualityOperators<Result<T>, Result<T>, bool>,
 {
 	/// <summary>
 	/// Checks whether two results are equal. Results are equal if both results are success values and the success
-	/// values are equal, or if both results are failures.
+	/// values are equal, or if both results are failures. Two failures are equal regardless of their error content.
 	/// </summary>
 	/// <param name="a">The first result to compare.</param>
 	/// <param name="b">The second result to compare.</param>