Adopt suggestions of #5590 (#5721)

* document `Stat$dropped_aes`

* replace `stat()` with `after_stat()`

* tweak ggproto docs

Author: teunbrand

R/ggproto.R

@@ -27,12 +27,20 @@
 #' To explicitly call a methods in a parent, use
 #' `ggproto_parent(Parent, self)`.
 #'
+#' @section Working with ggproto classes:
+#' The ggproto objects constructed are build on top of environments, which has
+#' some ramifications. Environments do not follow the 'copy on modify' semantics
+#' one might be accustomed to in regular objects. Instead they have
+#' ['modify in place'](https://adv-r.hadley.nz/names-values.html#env-modify)
+#' semantics.
+#'
 #' @param _class Class name to assign to the object. This is stored as the class
 #'   attribute of the object. This is optional: if `NULL` (the default),
 #'   no class name will be added to the object.
 #' @param _inherit ggproto object to inherit from. If `NULL`, don't
 #'   inherit from any object.
-#' @param ... A list of members in the ggproto object.
+#' @param ... A list of named members in the ggproto object. These can be
+#'   functions that become methods of the class or regular objects.
 #' @seealso
 #' The `r link_book("ggproto introduction section", "internals#sec-ggproto")`
 #' @export

R/stat-.R

@@ -45,6 +45,9 @@
 #'     render the geom.
 #'   - `default_aes`: A list (generated by [aes()] of
 #'     default values for aesthetics.
+#'   - `dropped_aes` is a vecor of aesthetic names that are safe to drop after
+#'     statistical transformation. A classic example is the `weight` aesthetic
+#'     that is consumed during computation of the stat.
 #'
 #' See also the `r link_book("new stats section", "extensions#sec-new-stats")`
 #' @rdname ggplot2-ggproto

man/ggplot2-ggproto.Rd

@@ -284,15 +284,15 @@ This stat illustrates another important point. If we want to make this stat usab
 #|  the kernel density estimate of the displacement."
 StatDensityCommon <- ggproto("StatDensity2", Stat, 
   required_aes = "x",
-  default_aes = aes(y = stat(density)),
+  default_aes = aes(y = after_stat(density)),
 
   compute_group = function(data, scales, bandwidth = 1) {
     d <- density(data$x, bw = bandwidth)
     data.frame(x = d$x, density = d$y)
   }  
 )
 
-ggplot(mpg, aes(displ, drv, colour = stat(density))) + 
+ggplot(mpg, aes(displ, drv, colour = after_stat(density))) + 
   stat_density_common(bandwidth = 1, geom = "point")
 ```
 
@@ -322,7 +322,7 @@ This is because each density is computed independently, and the estimated `x`s d
 #| )
 StatDensityCommon <- ggproto("StatDensityCommon", Stat, 
   required_aes = "x",
-  default_aes = aes(y = stat(density)),
+  default_aes = aes(y = after_stat(density)),
 
   setup_params = function(data, params) {
     min <- min(data$x) - 3 * params$bandwidth
@@ -344,7 +344,7 @@ StatDensityCommon <- ggproto("StatDensityCommon", Stat,
 
 ggplot(mpg, aes(displ, fill = drv)) + 
   stat_density_common(bandwidth = 1, geom = "area", position = "stack")
-ggplot(mpg, aes(displ, drv, fill = stat(density))) + 
+ggplot(mpg, aes(displ, drv, fill = after_stat(density))) + 
   stat_density_common(bandwidth = 1, geom = "raster")
 ```