Improve aes() news and documentation (#2677)

* Improve aes() news and documentation

Fixes #2676

Author: hadley

NEWS.md

@@ -10,11 +10,13 @@ To be released as 2.3.0
     introduction to tidy evaluation can be found in the meta programming
     chapters in [Advanced R](https://adv-r.hadley.nz).
 
-    The primary developer facing change is that `aes()` is now a list of 
-    quosures (expression + environment pairs) rather than a list of symbols,
-    and you'll need to take a different approach to extracting the information
-    you need. A common symptom of this change are errors "undefined columns 
-    selected" or "invalid 'type' (list) of argument" (#2610). 
+    The primary developer facing change is that `aes()` now contains 
+    quosures (expression + environment pairs) rather than symbols, and you'll 
+    need to take a different approach to extracting the information you need. 
+    A common symptom of this change are errors "undefined columns selected" or 
+    "invalid 'type' (list) of argument" (#2610). As in the previous version,
+    constants (like `aes(x = 1)` or `aes(colour = "smoothed")`) are stored
+    as is.
 
     In this version of ggplot2, you need to describe a mapping in a string, 
     use `quo_name()` (for shorter labels) or `quo_text()` (if you want 

R/aes.r

@@ -48,6 +48,8 @@ NULL
 #'   they are so common; all other aesthetics must be named.
 #' @seealso [vars()] for another quoting function designed for
 #'   faceting specifications.
+#' @return A list with class `uneval`. Components of the list are either
+#'   quosures or constants.
 #' @export
 #' @examples
 #' aes(x = mpg, y = wt)
@@ -56,32 +58,36 @@ NULL
 #' # You can also map aesthetics to functions of variables
 #' aes(x = mpg ^ 2, y = wt / cyl)
 #'
+#' # Or to constants
+#' aes(x = 1, colour = "smooth")
+#'
 #' # Aesthetic names are automatically standardised
 #' aes(col = x)
 #' aes(fg = x)
 #' aes(color = x)
 #' aes(colour = x)
 #'
-#' # aes is almost always used with ggplot() or a layer
+#' # aes() is passed to either ggplot() or specific layer. Aesthetics supplied
+#' # to ggplot() are used as defaults for every layer.
 #' ggplot(mpg, aes(displ, hwy)) + geom_point()
 #' ggplot(mpg) + geom_point(aes(displ, hwy))
 #'
-#' # Aesthetics supplied to ggplot() are used as defaults for every layer
-#' # you can override them, or supply different aesthetics for each layer
-#'
-#'
-#' # aes() is a quoting function, so you need to use tidy evaluation
-#' # techniques to create wrappers around ggplot2 pipelines. The
+#' # Tidy evaluation ----------------------------------------------------
+#' # aes() automatically quotes all its arguments, so you need to use tidy
+#' # evaluation to create wrappers around ggplot2 pipelines. The
 #' # simplest case occurs when your wrapper takes dots:
 #' scatter_by <- function(data, ...) {
 #'   ggplot(data) + geom_point(aes(...))
 #' }
 #' scatter_by(mtcars, disp, drat)
 #'
 #' # If your wrapper has a more specific interface with named arguments,
-#' # you need to use the "enquote and unquote" technique:
+#' # you need "enquote and unquote":
 #' scatter_by <- function(data, x, y) {
-#'   ggplot(data) + geom_point(aes(!!enquo(x), !!enquo(y)))
+#'   x <- enquo(x)
+#'   y <- enquo(y)
+#'
+#'   ggplot(data) + geom_point(aes(!!x, !!y))
 #' }
 #' scatter_by(mtcars, disp, drat)
 #'