Improve expect_s3_class() documentation

Fixes #2401

Author: hadley

R/expect-inheritance.R

@@ -18,9 +18,16 @@
 #' See [expect_vector()] for testing properties of objects created by vctrs.
 #'
 #' @param type String giving base type (as returned by [typeof()]).
-#' @param class Either a character vector of class names, or
-#'  for `expect_s3_class()` and `expect_s4_class()`, an `NA` to assert
-#'  that `object` isn't an S3 or S4 object.
+#' @param class
+#'
+#'  * `expect_type()` a single string giving an R base type.
+#'  * `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_s7_class()` an [S7::S7_class()] object.
 #' @inheritParams expect_that
 #' @family expectations
 #' @examples
@@ -31,6 +38,15 @@
 #' # A data frame is built from a list:
 #' expect_type(x, "list")
 #'
+#' f <- factor(c("a", "b", "c"))
+#' o <- ordered(f)
+#'
+#' # Using multiple class names tests if the object inherits from any of them
+#' expect_s3_class(f, c("ordered", "factor"))
+#' # Use exact = TRUE to test for exact match
+#' show_failure(expect_s3_class(f, c("ordered", "factor"), exact = TRUE))
+#' expect_s3_class(o, c("ordered", "factor"), exact = TRUE)
+#'
 #' # An integer vector is an atomic vector of type "integer"
 #' expect_type(x$x, "integer")
 #' # It is not an S3 object
@@ -66,8 +82,8 @@ expect_type <- function(object, type) {
 #' @export
 #' @rdname inheritance-expectations
 #' @param exact If `FALSE`, the default, checks that `object` inherits
-#'   from `class`. If `TRUE`, checks that object has a class that's identical
-#'   to `class`.
+#'   from any element of `class`. If `TRUE`, checks that object has a class
+#'   that's identical to `class`.
 expect_s3_class <- function(object, class, exact = FALSE) {
   act <- quasi_label(enquo(object))
   act$class <- format_class(class(act$val))
@@ -175,15 +191,16 @@ isS3 <- function(x) is.object(x) && !isS4(x)
 #'
 #' `expect_is()` is an older form that uses [inherits()] without checking
 #' whether `x` is S3, S4, or neither. Instead, I'd recommend using
-#' [expect_type()], [expect_s3_class()] or [expect_s4_class()] to more clearly
-#' convey your  intent.
+#' [expect_type()], [expect_s3_class()], or [expect_s4_class()] to more clearly
+#' convey your intent.
 #'
 #' @section 3rd edition:
 #' `r lifecycle::badge("deprecated")`
 #'
 #' `expect_is()` is formally deprecated in the 3rd edition.
 #'
 #' @keywords internal
+#' @param class Class name passed to `inherits()`.
 #' @inheritParams expect_type
 #' @export
 expect_is <- function(object, class, info = NULL, label = NULL) {