From 1699e6248b0b337cfe93f4564eb95d768c5eda69 Mon Sep 17 00:00:00 2001 From: Chua Chee Seng Date: Wed, 14 Jun 2023 23:01:42 +0800 Subject: [PATCH] Added scaladocs to Expectations. --- .../scalatest/expectations/Expectations.scala | 81 ++++++++++++++++- .../scalatest/expectations/Expectations.scala | 90 +++++++++++++++++-- 2 files changed, 162 insertions(+), 9 deletions(-) diff --git a/dotty/core/src/main/scala/org/scalatest/expectations/Expectations.scala b/dotty/core/src/main/scala/org/scalatest/expectations/Expectations.scala index 3c61295aa2..64897c578b 100644 --- a/dotty/core/src/main/scala/org/scalatest/expectations/Expectations.scala +++ b/dotty/core/src/main/scala/org/scalatest/expectations/Expectations.scala @@ -23,9 +23,21 @@ import scala.concurrent.Future import scala.reflect.ClassTag import scala.compiletime.testing.{typeChecks, typeCheckErrors} -private[scalatest] trait Expectations { +/** + * A representation of an expectation for an assertion. + * Expectations provide a way to express assertions that return a [[Fact]] object instead of throwing exceptions + * when the assertion fails. + */ +trait Expectations { - // TODO: Need to make this and assertResult use custom equality I think. + /** + * Asserts that `actual` is equal to `expected` using default equality. + * + * @param expected the expected value + * @param actual the actual value + * @param prettifier the prettifier used to pretty-print the values + * @return a [[Fact]] representing the result of the assertion + */ def expectResult(expected: Any)(actual: Any)(implicit prettifier: Prettifier): Fact = { if (!DefaultEquality.areEqualComparingArraysStructurally(actual, expected)) { val (act, exp) = Suite.getObjectsForFailureMessage(actual, expected) @@ -63,6 +75,14 @@ private[scalatest] trait Expectations { } } + /** + * Asserts that a block of code throws an exception of type `T`. + * + * @param f the block of code to be executed + * @param classTag the class tag representing the exception type `T` + * @param prettifier the prettifier used to pretty-print the values + * @return an [[Expectation]] representing the result of the assertion + */ def expectThrows[T <: AnyRef](f: => Any)(implicit classTag: ClassTag[T], prettifier: Prettifier): Expectation = { val clazz = classTag.runtimeClass try { @@ -108,33 +128,86 @@ private[scalatest] trait Expectations { } } + /** + * Asserts that a boolean expression is `true`. + * + * @param expression the boolean expression to be evaluated + * @param prettifier the prettifier used to pretty-print the values + * @return a [[Fact]] representing the result of the assertion + */ inline def expect(expression: Boolean)(implicit prettifier: Prettifier): Fact = ${ ExpectationsMacro.expect('{expression})('{prettifier}) } + /** + * Expects that a given code snippet does not compile. + * + * @param code the code snippet to be compiled + * @param prettifier the prettifier used to pretty-print the values + * @return a [[Fact]] representing the result of the assertion + */ transparent inline def expectDoesNotCompile(inline code: String)(implicit prettifier: Prettifier): Fact = ${ CompileMacro.expectDoesNotCompileImpl('code, '{typeChecks(code)}, 'prettifier) } + /** + * Expects that a given code snippet compiles successfully. + * + * @param code the code snippet to be compiled + * @param prettifier the prettifier used to pretty-print the values + * @return a [[Fact]] representing the result of the assertion + */ transparent inline def expectCompiles(inline code: String)(implicit prettifier: Prettifier): Fact = ${ CompileMacro.expectCompilesImpl('code, '{typeCheckErrors(code)}, 'prettifier) } + /** + * Expects that a given code snippet results in a type error during compilation. + * + * @param code the code snippet to be compiled + * @param prettifier the prettifier used to pretty-print the values + * @return a [[Fact]] representing the result of the assertion + */ transparent inline def expectTypeError(inline code: String)(implicit prettifier: Prettifier): Fact = ${ CompileMacro.expectTypeErrorImpl('code, '{typeCheckErrors(code)}, 'prettifier) } import scala.language.implicitConversions /** - * Implicit conversion that makes (x > 0) implies expect(x > -1) syntax works - */ + * Implicitly converts a boolean expression to a [[Fact]] for assertion purposes, which makes (x > 0) implies expect(x > -1) syntax works + * + * @param expression the boolean expression to be evaluated + * @param prettifier the prettifier used to pretty-print the values + * @param pos the source position + * @return a [[Fact]] representing the result of the assertion + */ implicit inline def booleanToFact(expression: Boolean)(implicit prettifier: Prettifier): Fact = ${ ExpectationsMacro.expect('expression)('prettifier) } + /** + * Implicitly converts an [[Expectation]] to an [[Assertion]]. + * + * @param exp the expectation to be converted + * @return an [[Assertion]] representing the result of the expectation + */ implicit def convertExpectationToAssertion(exp: Expectation): Assertion = exp.toAssertion } +/** + * The companion object for the `Expectation` trait. + */ object Expectations extends Expectations { + /** + * A helper used by macro-generated code. + */ class ExpectationsHelper { + /** + * A helper method for macro-generated assertions. + * + * @param bool the [[Bool]] object representing the assertion result + * @param clue the clue to be used in case of failure + * @param prettifier the prettifier used to pretty-print the values + * @return a [[Fact]] representing the result of the assertion + */ def macroExpect(bool: Bool, clue: Any, prettifier: Prettifier): Fact = { //requireNonNull(clue) if (!bool.value) diff --git a/jvm/core/src/main/scala/org/scalatest/expectations/Expectations.scala b/jvm/core/src/main/scala/org/scalatest/expectations/Expectations.scala index f69299ab77..109eeed41d 100644 --- a/jvm/core/src/main/scala/org/scalatest/expectations/Expectations.scala +++ b/jvm/core/src/main/scala/org/scalatest/expectations/Expectations.scala @@ -22,9 +22,22 @@ import scala.concurrent.ExecutionContext import scala.concurrent.Future import scala.reflect.ClassTag -private[scalatest] trait Expectations { +/** + * A representation of an expectation for an assertion. + * Expectations provide a way to express assertions that return a [[Fact]] object instead of throwing exceptions + * when the assertion fails. + */ +trait Expectations { - // TODO: Need to make this and assertResult use custom equality I think. + /** + * Asserts that `actual` is equal to `expected` using default equality. + * + * @param expected the expected value + * @param actual the actual value + * @param prettifier the prettifier used to pretty-print the values + * @param pos the source position + * @return a [[Fact]] representing the result of the assertion + */ def expectResult(expected: Any)(actual: Any)(implicit prettifier: Prettifier, pos: source.Position): Fact = { if (!DefaultEquality.areEqualComparingArraysStructurally(actual, expected)) { val (act, exp) = Suite.getObjectsForFailureMessage(actual, expected) @@ -62,6 +75,14 @@ private[scalatest] trait Expectations { } } + /** + * Asserts that a block of code throws an exception of type `T`. + * + * @param f the block of code to be executed + * @param classTag the class tag representing the exception type `T` + * @param prettifier the prettifier used to pretty-print the values + * @return an [[Expectation]] representing the result of the assertion + */ def expectThrows[T <: AnyRef](f: => Any)(implicit classTag: ClassTag[T], prettifier: Prettifier): Expectation = { val clazz = classTag.runtimeClass try { @@ -109,28 +130,87 @@ private[scalatest] trait Expectations { import language.experimental.macros + /** + * Asserts that a boolean expression is `true`. + * + * @param expression the boolean expression to be evaluated + * @param prettifier the prettifier used to pretty-print the values + * @param pos the source position + * @return a [[Fact]] representing the result of the assertion + */ def expect(expression: Boolean)(implicit prettifier: Prettifier, pos: source.Position): Fact = macro ExpectationsMacro.expect + /** + * Expects that a given code snippet does not compile. + * + * @param code the code snippet to be compiled + * @param prettifier the prettifier used to pretty-print the values + * @param pos the source position + * @return a [[Fact]] representing the result of the assertion + */ def expectDoesNotCompile(code: String)(implicit prettifier: Prettifier, pos: source.Position): Fact = macro CompileMacro.expectDoesNotCompileImpl + /** + * Expects that a given code snippet compiles successfully. + * + * @param code the code snippet to be compiled + * @param prettifier the prettifier used to pretty-print the values + * @param pos the source position + * @return a [[Fact]] representing the result of the assertion + */ def expectCompiles(code: String)(implicit prettifier: Prettifier, pos: source.Position): Fact = macro CompileMacro.expectCompilesImpl + /** + * Expects that a given code snippet results in a type error during compilation. + * + * @param code the code snippet to be compiled + * @param prettifier the prettifier used to pretty-print the values + * @param pos the source position + * @return a [[Fact]] representing the result of the assertion + */ def expectTypeError(code: String)(implicit prettifier: Prettifier, pos: source.Position): Fact = macro CompileMacro.expectTypeErrorImpl import scala.language.implicitConversions /** - * Implicit conversion that makes (x > 0) implies expect(x > -1) syntax works - */ + * Implicitly converts a boolean expression to a [[Fact]] for assertion purposes, which makes (x > 0) implies expect(x > -1) syntax works + * + * @param expression the boolean expression to be evaluated + * @param prettifier the prettifier used to pretty-print the values + * @param pos the source position + * @return a [[Fact]] representing the result of the assertion + */ implicit def booleanToFact(expression: Boolean)(implicit prettifier: Prettifier, pos: source.Position): Fact = macro ExpectationsMacro.expect + /** + * Implicitly converts an [[Expectation]] to an [[Assertion]]. + * + * @param exp the expectation to be converted + * @return an [[Assertion]] representing the result of the expectation + */ implicit def convertExpectationToAssertion(exp: Expectation): Assertion = exp.toAssertion } -private[scalatest] object Expectations extends Expectations { +/** + * The companion object for the `Expectation` trait. + */ +object Expectations extends Expectations { + + /** + * A helper used by macro-generated code. + */ class ExpectationsHelper { + /** + * A helper method for macro-generated assertions. + * + * @param bool the [[Bool]] object representing the assertion result + * @param clue the clue to be used in case of failure + * @param prettifier the prettifier used to pretty-print the values + * @param pos the source position + * @return a [[Fact]] representing the result of the assertion + */ def macroExpect(bool: Bool, clue: Any, prettifier: Prettifier, pos: source.Position): Fact = { //requireNonNull(clue) if (!bool.value)