Make vector recycling rules its own FAQ

R/faq-developer.R

@@ -12,6 +12,18 @@ NULL
 #' @name theory-faq-coercion
 NULL
 
+# The `@name` must be `vector_recycling_rules` to ensure a pkgdown page
+# continues to exist for `vector_recycling_rules` since other packages link to
+# this page and currently `@aliases` don't get a page on the pkgdown
+# site due to: https://github.com/r-lib/pkgdown/issues/1876
+#' FAQ - How does recycling work in vctrs and the tidyverse?
+#'
+#' @includeRmd man/faq/developer/theory-recycling.Rmd description
+#'
+#' @name vector_recycling_rules
+#' @aliases theory-faq-recycling
+NULL
+
 #' FAQ - How to implement ptype2 and cast methods?
 #'
 #' @includeRmd man/faq/developer/howto-coercion.Rmd description

R/recycle.R

@@ -1,75 +1,3 @@
-#' Recycling rules used by r-lib and the tidyverse
-#'
-#' @description
-#' Recycling describes the concept of repeating elements of one vector to match
-#' the size of another. There are two rules that underlie the "tidyverse"
-#' recycling rules:
-#'
-#' - Vectors of size 1 will be recycled to the size of any other vector
-#'
-#' - Otherwise, all vectors must have the same size
-#'
-#' @section Examples:
-#'
-#' ```{r, warning = FALSE, message = FALSE, include = FALSE}
-#' library(tibble)
-#' ```
-#'
-#' Vectors of size 1 are recycled to the size of any other vector:
-#'
-#' ```{r, comment = "#>"}
-#' tibble(x = 1:3, y = 1L)
-#' ```
-#'
-#' This includes vectors of size 0:
-#'
-#' ```{r, comment = "#>"}
-#' tibble(x = integer(), y = 1L)
-#' ```
-#'
-#' If vectors aren't size 1, they must all be the same size. Otherwise, an error
-#' is thrown:
-#'
-#' ```{r, comment = "#>", error = TRUE}
-#' tibble(x = 1:3, y = 4:7)
-#' ```
-#'
-#' @section vctrs backend:
-#'
-#' Packages in r-lib and the tidyverse generally use [vec_size_common()] and
-#' [vec_recycle_common()] as the backends for handling recycling rules.
-#'
-#' - `vec_size_common()` returns the common size of multiple vectors, after
-#'   applying the recycling rules
-#'
-#' - `vec_recycle_common()` goes one step further, and actually recycles the
-#'   vectors to their common size
-#'
-#' ```{r, comment = "#>", error = TRUE}
-#' vec_size_common(1:3, "x")
-#'
-#' vec_recycle_common(1:3, "x")
-#'
-#' vec_size_common(1:3, c("x", "y"))
-#' ```
-#'
-#' @section Base R recycling rules:
-#'
-#' The recycling rules described here are stricter than the ones generally used
-#' by base R, which are:
-#'
-#' - If any vector is length 0, the output will be length 0
-#'
-#' - Otherwise, the output will be length `max(length_x, length_y)`, and a
-#'   warning will be thrown if the length of the longer vector is not an integer
-#'   multiple of the length of the shorter vector.
-#'
-#' We explore the base R rules in detail in `vignette("type-size")`.
-#'
-#' @name vector_recycling_rules
-#' @keywords internal
-NULL
-
 #' Vector recycling
 #'
 #' `vec_recycle(x, size)` recycles a single vector to a given size.

man/faq/developer/theory-recycling.Rmd

@@ -0,0 +1,59 @@
+
+```{r, child = "../setup.Rmd", include = FALSE}
+```
+
+Recycling describes the concept of repeating elements of one vector to match the size of another. There are two rules that underlie the "tidyverse" recycling rules:
+
+- Vectors of size 1 will be recycled to the size of any other vector
+
+- Otherwise, all vectors must have the same size
+
+# Examples
+
+```{r, warning = FALSE, message = FALSE, include = FALSE}
+library(tibble)
+```
+
+Vectors of size 1 are recycled to the size of any other vector:
+
+```{r}
+tibble(x = 1:3, y = 1L)
+```
+
+This includes vectors of size 0:
+
+```{r}
+tibble(x = integer(), y = 1L)
+```
+
+If vectors aren't size 1, they must all be the same size. Otherwise, an error is thrown:
+
+```{r, error = TRUE}
+tibble(x = 1:3, y = 4:7)
+```
+
+# vctrs backend:
+
+Packages in r-lib and the tidyverse generally use [vec_size_common()] and [vec_recycle_common()] as the backends for handling recycling rules.
+
+- `vec_size_common()` returns the common size of multiple vectors, after applying the recycling rules
+
+- `vec_recycle_common()` goes one step further, and actually recycles the vectors to their common size
+
+```{r, error = TRUE}
+vec_size_common(1:3, "x")
+
+vec_recycle_common(1:3, "x")
+
+vec_size_common(1:3, c("x", "y"))
+```
+
+# Base R recycling rules:
+
+The recycling rules described here are stricter than the ones generally used by base R, which are:
+
+- If any vector is length 0, the output will be length 0
+
+- Otherwise, the output will be length `max(length_x, length_y)`, and a warning will be thrown if the length of the longer vector is not an integer multiple of the length of the shorter vector.
+
+We explore the base R rules in detail in `vignette("type-size")`.