Document expand() output with unrealized factor levels

R/step-subset-expand.R

@@ -2,7 +2,8 @@
 #'
 #' @description
 #' This is a method for the tidyr `expand()` generic. It is translated to
-#' [data.table::CJ()].
+#' [data.table::CJ()]. Unlike the data.frame method, this method only retains
+#' factor levels present in the data.
 #'
 #' @param data A [lazy_dt()].
 #' @inheritParams tidyr::expand
@@ -19,12 +20,26 @@
 #'   weights = rnorm(6, as.numeric(size) + 2)
 #' ))
 #'
-#' # All possible combinations ---------------------------------------
-#' # Note that all defined, but not necessarily present, levels of the
-#' # factor variable `size` are retained.
-#' fruits %>% expand(type)
-#' fruits %>% expand(type, size)
-#' fruits %>% expand(type, size, year)
+#' # Factors ----------------------------------------------------------
+#' # When called on `fruits` defined above, the level "L" is not present in
+#' # the output of `expand(fruits, size)`, unlike the output of `expand()` when
+#' # `fruits` is a data.frame.
+#'
+#' fruits %>% expand(size) %>% as_tibble()
+#' #> # A tibble: 3 × 1
+#' #>   size
+#' #>   <fct>
+#' #> 1 XS
+#' #> 2 S
+#' #> 3 M
+#' fruits %>% as_tibble() %>% expand(size)
+#' #> # A tibble: 4 × 1
+#' #>   size
+#' #>   <fct>
+#' #> 1 XS
+#' #> 2 S
+#' #> 3 M
+#' #> 4 L
 #'
 #' # Other uses -------------------------------------------------------
 #' fruits %>% expand(type, size, 2010:2012)