add to documentation

Author: yjunechoe

R/aes-evaluation.R

@@ -32,7 +32,7 @@
 #' Below follows an overview of the three stages of evaluation and how aesthetic
 #' evaluation can be controlled.
 #'
-#' ## Stage 1: direct input
+#' ## Stage 1: direct input at the start
 #' The default is to map at the beginning, using the layer data provided by
 #' the user. If you want to map directly from the layer data you should not do
 #' anything special. This is the only stage where the original layer data can
@@ -87,17 +87,19 @@
 #' ```
 #'
 #' ## Complex staging
-#' If you want to map the same aesthetic multiple times, e.g. map `x` to a
-#' data column for the stat, but remap it for the geom, you can use the
-#' `stage()` function to collect multiple mappings.
+#' Sometimes, you may want to map the same aesthetic multiple times, e.g. map
+#' `x` to a data column at the start for the layer stat, but remap it later to
+#' a variable from the stat transformation for the layer geom. The `stage()`
+#' function allows you to control multiple mappings for the same aesthetic
+#' across all three stages of evaluation.
 #'
 #' ```r
 #' # Use stage to modify the scaled fill
 #' ggplot(mpg, aes(class, hwy)) +
 #'   geom_boxplot(aes(fill = stage(class, after_scale = alpha(fill, 0.4))))
 #'
 #' # Using data for computing summary, but placing label elsewhere.
-#' # Also, we're making our own computed variable to use for the label.
+#' # Also, we're making our own computed variables to use for the label.
 #' ggplot(mpg, aes(class, displ)) +
 #'   geom_violin() +
 #'   stat_summary(
@@ -110,6 +112,11 @@
 #'   )
 #' ```
 #'
+#' Conceptually, `aes(x)` is equivalent to `aes(stage(start = x))`, and
+#' `aes(after_stat(count))` is equivalent to `aes(stage(after_stat = count))`,
+#' and so on. `stage()` is most useful when at least two of its arguments are
+#' specified.
+#'
 #' ## Theme access
 #' The `from_theme()` function can be used to acces the [`element_geom()`]
 #' fields of the `theme(geom)` argument. Using `aes(colour = from_theme(ink))`