Improve + documentation

Author: hadley

NEWS.md

@@ -159,6 +159,8 @@ There were a number of tweaks legend themes:
   stricter for aesthetics (previously there was no message), and less
   strict for parameters (previously this threw an error) (#1585).
 
+* `+.gg` now works for lists that include data frames.
+
 * `annotation_x()` now works in the absense of global data (#1655)
 
 * `geom_*(show.legend = FALSE)` now works for `guide_colorbar`

R/plot-construction.r

@@ -2,65 +2,61 @@
 #'
 #' This operator allows you to add objects to a ggplot or theme object.
 #'
-#' If the first object is an object of class \code{ggplot}, you can add
-#' the following types of objects, and it will return a modified ggplot
-#' object.
+#' @section Adding on to a ggplot object:
+#' You can add any of the following types of objects:
 #'
 #' \itemize{
-#'   \item \code{data.frame}: replace current data.frame
-#'      (must use \code{\%+\%})
 #'   \item \code{uneval}: replace current aesthetics
 #'   \item \code{layer}: add new layer
 #'   \item \code{theme}: update plot theme
 #'   \item \code{scale}: replace current scale
 #'   \item \code{coord}: override current coordinate system
 #'   \item \code{facet}: override current coordinate faceting
+#'   \item \code{list}: a list of any of the above.
 #' }
 #'
-#' If the first object is an object of class \code{theme}, you can add
-#' another theme object. This will return a modified theme object.
+#' To replace the current default data frame, you must use \code{\%+\%},
+#' due to S3 method precedence issues.
 #'
-#' For theme objects, the \code{+} operator and the \code{\%+replace\%}
-#' can be used to modify elements in themes.
+#' @section Adding on to a theme:
 #'
-#' The \code{+} operator updates the elements of e1 that differ from
-#' elements specified (not NULL) in e2.
-#' Thus this operator can be used to incrementally add or modify attributes
-#' of a ggplot theme.
+#' \code{+} and \code{\%+replace\%} can be used to modify elements in themes.
 #'
-#' In contrast, the \code{\%+replace\%} operator replaces the
-#' entire element; any element of a theme not specified in e2 will not be
-#' present in the resulting theme (i.e. NULL).
-#' Thus this operator can be used to overwrite an entire theme.
+#' \code{+} updates the elements of e1 that differ from elements specified (not
+#' NULL) in e2. Thus this operator can be used to incrementally add or modify
+#' attributes of a ggplot theme.
 #'
+#' In contrast, \code{\%+replace\%} replaces the entire element; any element of
+#' a theme not specified in e2 will not be present in the resulting theme (i.e.
+#' NULL). Thus this operator can be used to overwrite an entire theme.
+#'
+#' @param e1 An object of class \code{\link{ggplot}} or a \code{\link{theme}}.
+#' @param e2 A component, or list of components to add to \code{e1}.
+#' @seealso \code{\link{theme}}
+#' @export
+#' @method + gg
+#' @rdname gg-add
 #' @examples
-#' ### Adding objects to a ggplot object
-#' p <- ggplot(mtcars, aes(wt, mpg, colour = disp)) +
-#'   geom_point()
+#' # Adding on to a plot -----------------------------------------------
+#'
+#' base <- ggplot(mpg, aes(displ, hwy)) + geom_point()
+#' base + geom_smooth()
+#'
+#' # To override the data, you must use %+%
+#' base %+% subset(mpg, fl == "p")
 #'
-#' p
-#' p + coord_cartesian(ylim = c(0, 40))
-#' p + scale_colour_continuous(breaks = c(100, 300))
-#' p + guides(colour = "colourbar")
+#' # Alternatively, you can add multiple components with a list.
+#' # This can be useful to return from a list.
+#' base + list(subset(mpg, fl == "p"), geom_smooth())
 #'
-#' # Use a different data frame
-#' m <- mtcars[1:10, ]
-#' p %+% m
+#' # Adding on to a theme ----------------------------------------------
 #'
-#' ### Adding objects to a theme object
 #' # Compare these results of adding theme objects to other theme objects
 #' add_el <- theme_grey() + theme(text = element_text(family = "Times"))
 #' rep_el <- theme_grey() %+replace% theme(text = element_text(family = "Times"))
 #'
 #' add_el$text
 #' rep_el$text
-#'
-#' @param e1 An object of class \code{ggplot} or \code{theme}
-#' @param e2 A component to add to \code{e1}
-#' @export
-#' @seealso \code{\link{theme}}
-#' @method + gg
-#' @rdname gg-add
 "+.gg" <- function(e1, e2) {
   # Get the name of what was passed in as e2, and pass along so that it
   # can be displayed in error messages
@@ -75,7 +71,6 @@
 #' @export
 "%+%" <- `+.gg`
 
-
 add_ggplot <- function(p, object, objectname) {
   if (is.null(object)) return(p)
 
@@ -106,7 +101,7 @@ add_ggplot <- function(p, object, objectname) {
       p
   } else if (is.list(object)) {
     for (o in object) {
-      p <- p + o
+      p <- p %+% o
     }
   } else if (is.layer(object)) {
     p$layers <- append(p$layers, object)