Improved stat_function() documentation #3362

R/geom-point.r

@@ -35,7 +35,6 @@
 #'   often aesthetics, used to set an aesthetic to a fixed value, like
 #'   `colour = "red"` or `size = 3`. They may also be parameters
 #'   to the paired geom/stat.
-#' @inheritParams layer
 #' @export
 #' @examples
 #' p <- ggplot(mtcars, aes(wt, mpg))

R/stat-function.r

@@ -4,13 +4,13 @@
 #' The function is called with a grid of evenly spaced values along the x axis,
 #' and the results are drawn (by default) with a line.
 #'
-#' @eval rd_aesthetics("stat", "function")
+#'
 #' @param fun Function to use. Either 1) an anonymous function in the base or
 #'   rlang formula syntax (see [rlang::as_function()])
 #'   or 2) a quoted or character name referencing a function; see examples. Must
 #'   be vectorised.
 #' @param n Number of points to interpolate along
-#' @param args List of additional arguments to pass to `fun`
+#' @param args List of additional arguments passed on to the function defined by `fun`.
 #' @param xlim Optionally, restrict the range of the function to this range.
 #' @inheritParams layer
 #' @inheritParams geom_point
@@ -64,6 +64,15 @@ stat_function <- function(mapping = NULL, data = NULL,
                           na.rm = FALSE,
                           show.legend = NA,
                           inherit.aes = TRUE) {
+
+  # Warn if supplied mapping and/or data is going to be overwritten
+  if (!is.null(mapping)) {
+    warning("`mapping` is not used by stat_function()", call. = FALSE)
+  }
+  if (!is.null(data)) {
+    warning("`data` is not used by stat_function()", call. = FALSE)
+  }
+
   layer(
     data = data,
     mapping = mapping,

tests/testthat/test-stats-function.r

@@ -47,3 +47,11 @@ test_that("works with formula syntax", {
   expect_equal(ret$x, s)
   expect_equal(ret$y, s^2)
 })
+
+test_that("`mapping` is not used by stat_function()", {
+  expect_warning(stat_function(aes(), fun = identity), "`mapping` is not used")
+})
+
+test_that("`data` is not used by stat_function()", {
+  expect_warning(stat_function(data = mtcars, fun = identity), "`data` is not used")
+})