Extra documentation for ggplot_add() (#5968)

R/plot-construction.R

@@ -84,9 +84,32 @@ add_ggplot <- function(p, object, objectname) {
 #' @param object_name The name of the object to add
 #'
 #' @return A modified ggplot object
+#' @details
+#' Custom methods for `ggplot_add()` are intended to update the `plot` variable
+#' using information from a custom `object`. This can become convenient when
+#' writing extensions that don't build on the pre-existing grammar like
+#' layers, facets, coords and themes. The `ggplot_add()` function is never
+#' intended to be used directly, but it is triggered when an object is added
+#' to a plot via the `+` operator. Please note that the full `plot` object is
+#' exposed at this point, which comes with the responsibility of returning
+#' the plot intact.
 #'
 #' @keywords internal
 #' @export
+#' @examples
+#' # making a new method for the generic
+#' # in this example, we apply a text element to the text theme setting
+#' ggplot_add.element_text <- function(object, plot, object_name) {
+#' plot + theme(text = object)
+#' }
+#'
+#' # we can now use `+` to add our object to a plot
+#' ggplot(mpg, aes(displ, cty)) +
+#' geom_point() +
+#' element_text(colour = "red")
+#'
+#' # clean-up
+#' rm(ggplot_add.element_text)
 ggplot_add <- function(object, plot, object_name) {
  UseMethod("ggplot_add")
 }
@@ -152,7 +175,7 @@ ggplot_add.Facet <- function(object, plot, object_name) {
 #' @export
 ggplot_add.list <- function(object, plot, object_name) {
  for (o in object) {
- plot <- plot %+% o
+ plot <- ggplot_add(o, plot, object_name)
  }
  plot
 }