From 82fa14a4e37739d413e83b72bd3f81ab5c22dd49 Mon Sep 17 00:00:00 2001 From: Hadley Wickham Date: Mon, 4 Aug 2025 13:18:15 -0500 Subject: [PATCH 1/3] Clarify types in class expectations Fixes #1989 --- R/expect-inheritance.R | 6 +++--- man/inheritance-expectations.Rd | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/R/expect-inheritance.R b/R/expect-inheritance.R index 58dd72b84..c551d6c0f 100644 --- a/R/expect-inheritance.R +++ b/R/expect-inheritance.R @@ -21,13 +21,13 @@ #' #' @param type String giving base type (as returned by [typeof()]). #' @param class -#' * `expect_type()`: a single string giving an R base type. +#' * `expect_type()`: a string. #' * `expect_s3_class()`: a character vector of class names or `NA` to assert #' that `object` isn't an S3 object. If you provide multiple class names, #' the test will pass if `object` inherits from any of them, unless #' `exact = TRUE`. -#' * `expect_s4_class()`: a character vector of class names or `NA` to assert -#' that `object` isn't an S4 object. +#' * `expect_s4_class()`: a string or `NA` to assert that `object` isn't an +#' S4 object. #' * `expect_r6_class()`: a string. #' * `expect_s7_class()`: an [S7::S7_class()] object. #' @inheritParams expect_that diff --git a/man/inheritance-expectations.Rd b/man/inheritance-expectations.Rd index 5d678b9d9..1a5be0615 100644 --- a/man/inheritance-expectations.Rd +++ b/man/inheritance-expectations.Rd @@ -29,13 +29,13 @@ within a function or for loop. See \link{quasi_label} for more details.} \item{type}{String giving base type (as returned by \code{\link[=typeof]{typeof()}}).} \item{class}{\itemize{ -\item \code{expect_type()}: a single string giving an R base type. +\item \code{expect_type()}: a string. \item \code{expect_s3_class()}: a character vector of class names or \code{NA} to assert that \code{object} isn't an S3 object. If you provide multiple class names, the test will pass if \code{object} inherits from any of them, unless \code{exact = TRUE}. -\item \code{expect_s4_class()}: a character vector of class names or \code{NA} to assert -that \code{object} isn't an S4 object. +\item \code{expect_s4_class()}: a string or \code{NA} to assert that \code{object} isn't an +S4 object. \item \code{expect_r6_class()}: a string. \item \code{expect_s7_class()}: an \code{\link[S7:S7_class]{S7::S7_class()}} object. }} From 3b7836d8d4567c9c224067037b724aca88b0076a Mon Sep 17 00:00:00 2001 From: Hadley Wickham Date: Mon, 4 Aug 2025 14:23:40 -0500 Subject: [PATCH 2/3] Move not into a separate section --- R/expect-inheritance.R | 22 ++++++++++++---------- man/inheritance-expectations.Rd | 17 ++++++++++------- 2 files changed, 22 insertions(+), 17 deletions(-) diff --git a/R/expect-inheritance.R b/R/expect-inheritance.R index c551d6c0f..7c58662f8 100644 --- a/R/expect-inheritance.R +++ b/R/expect-inheritance.R @@ -20,16 +20,18 @@ #' See [expect_vector()] for testing properties of objects created by vctrs. #' #' @param type String giving base type (as returned by [typeof()]). -#' @param class -#' * `expect_type()`: a string. -#' * `expect_s3_class()`: a character vector of class names or `NA` to assert -#' that `object` isn't an S3 object. If you provide multiple class names, -#' the test will pass if `object` inherits from any of them, unless -#' `exact = TRUE`. -#' * `expect_s4_class()`: a string or `NA` to assert that `object` isn't an -#' S4 object. -#' * `expect_r6_class()`: a string. -#' * `expect_s7_class()`: an [S7::S7_class()] object. +#' @param class The different +#' * `expect_type()`: a string. +#' * `expect_s3_class()`: a character vector of class names. If you provide +#' multiple class names, the test will pass if `object` inherits from any +#' of them, unless `exact = TRUE`. +#' * `expect_s4_class()`: a string or `NA` to assert that `object` is not an +#' S4 object. +#' * `expect_r6_class()`: a string. +#' * `expect_s7_class()`: an [S7::S7_class()] object. +#' +#' For historical reasons, `expect_s3_class()` and `expect_s4_class()` take +#' `NA` to assert that the `object` is not an S3 or S4 object. #' @inheritParams expect_that #' @family expectations #' @examples diff --git a/man/inheritance-expectations.Rd b/man/inheritance-expectations.Rd index 1a5be0615..fdae73e3c 100644 --- a/man/inheritance-expectations.Rd +++ b/man/inheritance-expectations.Rd @@ -28,17 +28,20 @@ within a function or for loop. See \link{quasi_label} for more details.} \item{type}{String giving base type (as returned by \code{\link[=typeof]{typeof()}}).} -\item{class}{\itemize{ +\item{class}{The different +\itemize{ \item \code{expect_type()}: a string. -\item \code{expect_s3_class()}: a character vector of class names or \code{NA} to assert -that \code{object} isn't an S3 object. If you provide multiple class names, -the test will pass if \code{object} inherits from any of them, unless -\code{exact = TRUE}. -\item \code{expect_s4_class()}: a string or \code{NA} to assert that \code{object} isn't an +\item \code{expect_s3_class()}: a character vector of class names. If you provide +multiple class names, the test will pass if \code{object} inherits from any +of them, unless \code{exact = TRUE}. +\item \code{expect_s4_class()}: a string or \code{NA} to assert that \code{object} is not an S4 object. \item \code{expect_r6_class()}: a string. \item \code{expect_s7_class()}: an \code{\link[S7:S7_class]{S7::S7_class()}} object. -}} +} + +For historical reasons, \code{expect_s3_class()} and \code{expect_s4_class()} take +\code{NA} to assert that the \code{object} is not an S3 or S4 object.} \item{exact}{If \code{FALSE}, the default, checks that \code{object} inherits from any element of \code{class}. If \code{TRUE}, checks that object has a class From de2272e93d9349f6b3509de8b15ee400ab508eb1 Mon Sep 17 00:00:00 2001 From: Hadley Wickham Date: Mon, 4 Aug 2025 16:04:50 -0500 Subject: [PATCH 3/3] More polishing --- R/expect-inheritance.R | 17 ++++++++--------- man/inheritance-expectations.Rd | 17 ++++++++--------- 2 files changed, 16 insertions(+), 18 deletions(-) diff --git a/R/expect-inheritance.R b/R/expect-inheritance.R index 7c58662f8..3238fcdc7 100644 --- a/R/expect-inheritance.R +++ b/R/expect-inheritance.R @@ -20,18 +20,17 @@ #' See [expect_vector()] for testing properties of objects created by vctrs. #' #' @param type String giving base type (as returned by [typeof()]). -#' @param class The different +#' @param class The required type varies depending on the function: #' * `expect_type()`: a string. -#' * `expect_s3_class()`: a character vector of class names. If you provide -#' multiple class names, the test will pass if `object` inherits from any -#' of them, unless `exact = TRUE`. -#' * `expect_s4_class()`: a string or `NA` to assert that `object` is not an -#' S4 object. +#' * `expect_s3_class()`: a string or character vector. The behaviour of +#' multiple values (i.e. a character vector) is controlled by the +#' `exact` argument. +#' * `expect_s4_class()`: a string. #' * `expect_r6_class()`: a string. #' * `expect_s7_class()`: an [S7::S7_class()] object. #' -#' For historical reasons, `expect_s3_class()` and `expect_s4_class()` take -#' `NA` to assert that the `object` is not an S3 or S4 object. +#' For historical reasons, `expect_s3_class()` and `expect_s4_class()` also +#' take `NA` to assert that the `object` is not an S3 or S4 object. #' @inheritParams expect_that #' @family expectations #' @examples @@ -87,7 +86,7 @@ expect_type <- function(object, type) { #' @rdname inheritance-expectations #' @param exact If `FALSE`, the default, checks that `object` inherits #' from any element of `class`. If `TRUE`, checks that object has a class -#' that's identical to `class`. +#' that exactly matches `class`. expect_s3_class <- function(object, class, exact = FALSE) { check_bool(exact) diff --git a/man/inheritance-expectations.Rd b/man/inheritance-expectations.Rd index fdae73e3c..41ae792de 100644 --- a/man/inheritance-expectations.Rd +++ b/man/inheritance-expectations.Rd @@ -28,24 +28,23 @@ within a function or for loop. See \link{quasi_label} for more details.} \item{type}{String giving base type (as returned by \code{\link[=typeof]{typeof()}}).} -\item{class}{The different +\item{class}{The required type varies depending on the function: \itemize{ \item \code{expect_type()}: a string. -\item \code{expect_s3_class()}: a character vector of class names. If you provide -multiple class names, the test will pass if \code{object} inherits from any -of them, unless \code{exact = TRUE}. -\item \code{expect_s4_class()}: a string or \code{NA} to assert that \code{object} is not an -S4 object. +\item \code{expect_s3_class()}: a string or character vector. The behaviour of +multiple values (i.e. a character vector) is controlled by the +\code{exact} argument. +\item \code{expect_s4_class()}: a string. \item \code{expect_r6_class()}: a string. \item \code{expect_s7_class()}: an \code{\link[S7:S7_class]{S7::S7_class()}} object. } -For historical reasons, \code{expect_s3_class()} and \code{expect_s4_class()} take -\code{NA} to assert that the \code{object} is not an S3 or S4 object.} +For historical reasons, \code{expect_s3_class()} and \code{expect_s4_class()} also +take \code{NA} to assert that the \code{object} is not an S3 or S4 object.} \item{exact}{If \code{FALSE}, the default, checks that \code{object} inherits from any element of \code{class}. If \code{TRUE}, checks that object has a class -that's identical to \code{class}.} +that exactly matches \code{class}.} } \description{ See \url{https://adv-r.hadley.nz/oo.html} for an overview of R's OO systems, and