docs: improve error messages and XML documentation

Source/Testably.Expectations/Core/ExpectationBuilders/SimpleExpectationBuilder.cs

@@ -17,6 +17,11 @@ public ExpectationResult ApplyTo<TExpectation>(TExpectation actual)
 			return typedExpectation.IsMetBy(actual);
 		}
 
+		if (_expectation is null)
+		{
+			throw new InvalidOperationException("The expectation is incomplete! Did you add a trailing `.And()` or `.Or()` without specifying a second expectation?");
+		}
+
 		throw new InvalidOperationException(
 			$"The expectation does not support {typeof(TExpectation).Name} {actual}");
 	}

Source/Testably.Expectations/Core/ExpectationShould.cs

@@ -15,22 +15,22 @@ internal ExpectationShould(IExpectationBuilderStart expectationBuilder)
 	}
 
 	/// <summary>
-	///     Expect the actual value to be...
+	///     Expect the actual value to be…
 	/// </summary>
 	public ShouldBe Be => new(_expectationBuilder);
 
 	/// <summary>
-	///     Expect the actual value to end...
+	///     Expect the actual value to end…
 	/// </summary>
 	public ShouldEnd End => new(_expectationBuilder);
 
 	/// <summary>
-	///     Expect the actual value to start...
+	///     Expect the actual value to start…
 	/// </summary>
 	public ShouldStart Start => new(_expectationBuilder);
 
 	/// <summary>
-	///     Expect the actual value to throw...
+	///     Expect the actual value to throw…
 	/// </summary>
 	public ShouldThrow Throw => new(_expectationBuilder);
 }

Source/Testably.Expectations/Core/ExpectationWhichShould.cs

@@ -15,35 +15,35 @@ public class ExpectationWhichShould<TStart, TCurrent> : Expectation<TStart, TCur
 	public ExpectationShould Not => new(_expectationBuilder is IExpectationBuilderCombination b ? b.ReplaceRight(new NotExpectationBuilder(new SimpleExpectationBuilder())) : new NotExpectationBuilder(_expectationBuilder));
 
 	/// <summary>
-	///     Expect the actual value to be...
+	///     Expect the actual value to be…
 	/// </summary>
 	public ShouldBe Be => new(_expectationBuilder);
 
 	/// <summary>
-	///     Expect the actual value to end...
+	///     Expect the actual value to end…
 	/// </summary>
 	public ShouldEnd End => new(_expectationBuilder);
 
 	/// <summary>
-	///     Expect the actual value to start...
+	///     Expect the actual value to start…
 	/// </summary>
 	public ShouldStart Start => new(_expectationBuilder);
 
 	/// <summary>
-	///     Expect the actual value to throw...
+	///     Expect the actual value to throw…
 	/// </summary>
 	public ShouldThrow Throw => new(_expectationBuilder);
 
 	private readonly IExpectationBuilderStart _expectationBuilder;
 
-	internal ExpectationWhichShould(IExpectationBuilderStart expectationBuilder) : base(
-		expectationBuilder)
+	internal ExpectationWhichShould(IExpectationBuilderStart expectationBuilder)
+		: base(expectationBuilder)
 	{
 		_expectationBuilder = expectationBuilder;
 	}
 
 	/// <summary>
-	///     Accesses a property from <typeparamref name="TCurrent" /> and add an <paramref name="expectation" /> on it.
+	///     Specifies an <paramref name="expectation"/> on a property from <typeparamref name="TCurrent" />.
 	/// </summary>
 	/// <remarks>
 	///     The <paramref name="propertySelector" /> specifies which property to use.

Source/Testably.Expectations/Core/ShouldBe.cs

@@ -3,7 +3,7 @@
 namespace Testably.Expectations.Core;
 
 /// <summary>
-///     Expect the actual value to be...
+///     Expect the actual value to be…
 /// </summary>
 public class ShouldBe : ShouldVerb
 {

Source/Testably.Expectations/Core/ShouldEnd.cs

@@ -3,7 +3,7 @@
 namespace Testably.Expectations.Core;
 
 /// <summary>
-///     Expect the actual value to end...
+///     Expect the actual value to end…
 /// </summary>
 public class ShouldEnd : ShouldVerb
 {

Source/Testably.Expectations/Core/ShouldStart.cs

@@ -3,7 +3,7 @@
 namespace Testably.Expectations.Core;
 
 /// <summary>
-///     Expect the actual value to start...
+///     Expect the actual value to start…
 /// </summary>
 public class ShouldStart : ShouldVerb
 {

Source/Testably.Expectations/Core/ShouldThrow.cs

@@ -3,7 +3,7 @@
 namespace Testably.Expectations.Core;
 
 /// <summary>
-///     Expect the actual value to throw...
+///     Expect the actual value to throw…
 /// </summary>
 public class ShouldThrow : ShouldVerb
 {

Source/Testably.Expectations/Expect.cs

@@ -7,14 +7,17 @@
 namespace Testably.Expectations;
 
 /// <summary>
-///     Starting point for checking expectations.
+///     The starting point for checking expectations.
 /// </summary>
 [StackTraceHidden]
 public static class Expect
 {
 	/// <summary>
-	///     Define an <paramref name="expectation" /> on the <paramref name="actual" /> value.
+	///     Checks that the <paramref name="actual" /> value meets the <paramref name="expectation" />.
 	/// </summary>
+	/// <remarks>
+	///     Throws when the <paramref name="actual" /> value is <see langword="null" />.
+	/// </remarks>
 	public static void That<TActual, TTarget>([NotNull] TActual actual,
 		Expectation<TActual, TTarget> expectation,
 		[CallerArgumentExpression(nameof(actual))]
@@ -33,14 +36,17 @@ public static void That<TActual, TTarget>([NotNull] TActual actual,
 	}
 
 	/// <summary>
-	///     Define a <paramref name="nullableExpectation" /> on the <paramref name="actual" /> value.
+	///     Checks that the <paramref name="actual" /> value meets the <paramref name="expectation" />.
 	/// </summary>
+	/// <remarks>
+	///     The <paramref name="actual" /> value can be <see langword="null" />.
+	/// </remarks>
 	public static void That<TActual, TTarget>(TActual? actual,
-		NullableExpectation<TActual, TTarget> nullableExpectation,
+		NullableExpectation<TActual, TTarget> expectation,
 		[CallerArgumentExpression(nameof(actual))]
 		string actualExpression = "")
 	{
-		ExpectationResult result = nullableExpectation.ApplyTo(actual);
+		ExpectationResult result = expectation.ApplyTo(actual);
 
 		if (result is ExpectationResult.Failure failure)
 		{

Source/Testably.Expectations/ExpectationExtensions.cs

@@ -16,57 +16,57 @@ namespace Testably.Expectations;
 public static class ExpectationExtensions
 {
 	/// <summary>
-	///     Expects the actual value to be equal to <paramref name="expected" />.
+	///     Expect the actual value to be equal to <paramref name="expected" />.
 	/// </summary>
 	public static NullableExpectation<T?> EqualTo<T>(this ShouldBe shouldBe, T expected)
 		=> shouldBe.WithExpectation(new BeEqualTo<T?>(expected));
 
 	/// <summary>
-	///     Expects the <see cref="Action" /> to throw an exception.
+	///     Expect the <see cref="Action" /> to throw an exception.
 	/// </summary>
 	public static ExpectationWhichShould<Action, Exception> Exception(this ShouldThrow shouldThrow)
 		=> shouldThrow.WithExpectation(new ThrowException<Exception>());
 
 	/// <summary>
-	///     Expects the actual value to be <see langword="false" />.
+	///     Expect the actual value to be <see langword="false" />.
 	/// </summary>
 	public static Expectation<bool> False(this ShouldBe shouldBe)
 		=> shouldBe.WithExpectation(new BeFalse());
 
 	/// <summary>
-	///     Expects the actual value to be greater than <paramref name="expected" />.
+	///     Expect the actual value to be greater than <paramref name="expected" />.
 	/// </summary>
 	public static Expectation<int> GreaterThan(this ShouldBe shouldBe, int expected)
 		=> shouldBe.WithExpectation(new BeGreaterThan(expected));
 
 	/// <summary>
-	///     Expects the actual value to be <see langword="null" />.
+	///     Expect the actual value to be <see langword="null" />.
 	/// </summary>
 	public static NullableExpectation<object?> Null(this ShouldBe shouldBe)
 		=> shouldBe.WithExpectation(new BeNull<object?>());
 
 	/// <summary>
-	///     Expects the actual value to be of type <typeparamref name="TType" />.
+	///     Expect the actual value to be of type <typeparamref name="TType" />.
 	/// </summary>
 	public static ExpectationWhichShould<object?, TType> OfType<TType>(this ShouldBe shouldBe)
 		=> shouldBe.WithExpectation(new BeOfType<TType>());
 
 	/// <summary>
-	///     Expects the actual value to be <see langword="true" />.
+	///     Expect the actual value to be <see langword="true" />.
 	/// </summary>
 	public static Expectation<bool> True(this ShouldBe shouldBe)
 		=> shouldBe.WithExpectation(new BeTrue());
 
 	/// <summary>
-	///     Expects the <see cref="Action" /> to throw an exception of type <typeparamref name="TException" />.
+	///     Expect the <see cref="Action" /> to throw an exception of type <typeparamref name="TException" />.
 	/// </summary>
 	public static ExpectationWhichShould<Action, TException> TypeOf<TException>(
 		this ShouldThrow shouldThrow)
 		where TException : Exception
 		=> shouldThrow.WithExpectation(new ThrowException<TException>());
 
 	/// <summary>
-	///     Expects the <typeparamref name="TException" /> to have a message that meets the <paramref name="expectation" />.
+	///     Expect the <typeparamref name="TException" /> to have a message that meets the <paramref name="expectation" />.
 	/// </summary>
 	public static Expectation<TStart, TException> WhichMessage<TStart, TException>(
 		this ExpectationWhichShould<TStart, TException> whichShould,
@@ -75,13 +75,13 @@ public static Expectation<TStart, TException> WhichMessage<TStart, TException>(
 		=> whichShould.Which(m => m.Message, expectation);
 
 	/// <summary>
-	///     Expects the actual value to start with the <paramref name="expected" /> string.
+	///     Expect the actual value to start with the <paramref name="expected" /> string.
 	/// </summary>
 	public static Expectation<string?> With(this ShouldStart shouldStart, string expected)
 		=> shouldStart.WithExpectation(new StartWith(expected));
 
 	/// <summary>
-	///     Expects the actual value to end with the <paramref name="expected" /> string.
+	///     Expect the actual value to end with the <paramref name="expected" /> string.
 	/// </summary>
 	public static Expectation<string?> With(this ShouldEnd shouldEnd, string expected)
 		=> shouldEnd.WithExpectation(new EndWith(expected));

Source/Testably.Expectations/Should.cs

@@ -5,7 +5,7 @@
 namespace Testably.Expectations;
 
 /// <summary>
-///     Starting point for defining expectations.
+///     The starting point for defining expectations.
 /// </summary>
 [StackTraceHidden]
 public static class Should
@@ -16,22 +16,22 @@ public static class Should
 	public static ExpectationShould Not => new(new NotExpectationBuilder(new SimpleExpectationBuilder()));
 
 	/// <summary>
-	///     Expect the actual value to be...
+	///     Expect the actual value to be…
 	/// </summary>
 	public static ShouldBe Be => new(new SimpleExpectationBuilder());
 
 	/// <summary>
-	///     Expect the actual value to end...
+	///     Expect the actual value to end…
 	/// </summary>
 	public static ShouldEnd End => new(new SimpleExpectationBuilder());
 
 	/// <summary>
-	///     Expect the actual value to start...
+	///     Expect the actual value to start…
 	/// </summary>
 	public static ShouldStart Start => new(new SimpleExpectationBuilder());
 
 	/// <summary>
-	///     Expect the actual value to throw...
+	///     Expect the actual value to throw…
 	/// </summary>
 	public static ShouldThrow Throw => new(new SimpleExpectationBuilder());
 }

Tests/Testably.Expectations.Tests/Core/ExpectationBuilders/AndExpectationBuilderTests.cs

@@ -1,4 +1,5 @@
-using Testably.Expectations.Tests.TestHelpers;
+using System;
+using Testably.Expectations.Tests.TestHelpers;
 using Xunit;
 
 namespace Testably.Expectations.Tests.Core.ExpectationBuilders;
@@ -27,6 +28,17 @@ void Act()
 			Should.Be.EqualTo("Expected 1 to be A and to be B, but found D.")));
 	}
 
+	[Fact]
+	public void WithTrailingAnd_ShouldThrowInvalidOperationException()
+	{
+		void Act()
+			=> Expect.That(1,
+				Should.Be.AFailedTest("to be A", "found C").And());
+
+		Expect.That(Act, Should.Throw.TypeOf<InvalidOperationException>().WhichMessage(
+			Should.Be.EqualTo("The expectation is incomplete! Did you add a trailing `.And()` or `.Or()` without specifying a second expectation?")));
+	}
+
 	[Fact]
 	public void WithTwoFailedTests_ShouldIncludeBothFailuresInMessage()
 	{

Tests/Testably.Expectations.Tests/Core/ExpectationBuilders/OrExpectationBuilderTests.cs

@@ -1,4 +1,5 @@
-using Testably.Expectations.Tests.TestHelpers;
+using System;
+using Testably.Expectations.Tests.TestHelpers;
 using Xunit;
 
 namespace Testably.Expectations.Tests.Core.ExpectationBuilders;
@@ -17,6 +18,17 @@ public void WithSecondFailedTests_ShouldNotThrow()
 		Expect.That(1, Should.Be.ASuccessfulTest().Or().Be.AFailedTest("to be B", "found D"));
 	}
 
+	[Fact]
+	public void WithTrailingOr_ShouldThrowInvalidOperationException()
+	{
+		void Act()
+			=> Expect.That(1,
+				Should.Be.AFailedTest("to be A", "found C").Or());
+
+		Expect.That(Act, Should.Throw.TypeOf<InvalidOperationException>().WhichMessage(
+			Should.Be.EqualTo("The expectation is incomplete! Did you add a trailing `.And()` or `.Or()` without specifying a second expectation?")));
+	}
+
 	[Fact]
 	public void WithTwoFailedTests_ShouldIncludeBothFailuresInMessage()
 	{