From 6d2ed6de1cd367f79e432b81d7faa8dce411ca0e Mon Sep 17 00:00:00 2001
From: Teun van den Brand <49372158+teunbrand@users.noreply.github.com>
Date: Mon, 26 Aug 2024 13:14:14 +0200
Subject: [PATCH] Extra documentation for `ggplot_add()` (#5968)

---
 R/plot-construction.R | 25 ++++++++++++++++++++++++-
 man/ggplot_add.Rd     | 25 +++++++++++++++++++++++++
 2 files changed, 49 insertions(+), 1 deletion(-)

diff --git a/R/plot-construction.R b/R/plot-construction.R
index de1306098f..43a3f5b494 100644
--- a/R/plot-construction.R
+++ b/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
 }
diff --git a/man/ggplot_add.Rd b/man/ggplot_add.Rd
index 0bd2e2a698..c71d6f863e 100644
--- a/man/ggplot_add.Rd
+++ b/man/ggplot_add.Rd
@@ -20,4 +20,29 @@ A modified ggplot object
 This generic allows you to add your own methods for adding custom objects to
 a ggplot with \link{+.gg}.
 }
+\details{
+Custom methods for \code{ggplot_add()} are intended to update the \code{plot} variable
+using information from a custom \code{object}. This can become convenient when
+writing extensions that don't build on the pre-existing grammar like
+layers, facets, coords and themes. The \code{ggplot_add()} function is never
+intended to be used directly, but it is triggered when an object is added
+to a plot via the \code{+} operator. Please note that the full \code{plot} object is
+exposed at this point, which comes with the responsibility of returning
+the plot intact.
+}
+\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)
+}
 \keyword{internal}