From 1ca6a390406a33c23bfa3ad4b2414871b1aa0da1 Mon Sep 17 00:00:00 2001
From: Teun van den Brand <tahvdbrand@gmail.com>
Date: Thu, 5 Sep 2024 11:50:01 +0200
Subject: [PATCH] document

---
 NAMESPACE   | 1 +
 NEWS.md     | 2 ++
 R/labels.R  | 5 +++++
 man/labs.Rd | 7 +++++++
 4 files changed, 15 insertions(+)

diff --git a/NAMESPACE b/NAMESPACE
index f0ccf3bec1..1220e7e6ef 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -426,6 +426,7 @@ export(get_alt_text)
 export(get_element_tree)
 export(get_geom_defaults)
 export(get_guide_data)
+export(get_labs)
 export(get_last_plot)
 export(get_layer_data)
 export(get_layer_grob)
diff --git a/NEWS.md b/NEWS.md
index 40bdb3d156..75579e6fc6 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,5 +1,7 @@
 # ggplot2 (development version)
 
+* New `get_labs()` function for retrieving completed plot labels 
+  (@teunbrand, #6008).
 * `guide_bins()`, `guide_colourbar()` and `guide_coloursteps()` gain an `angle`
   argument to overrule theme settings, similar to `guide_axis(angle)` 
   (@teunbrand, #4594).
diff --git a/R/labels.R b/R/labels.R
index 16dfa2da3a..50e3776555 100644
--- a/R/labels.R
+++ b/R/labels.R
@@ -179,6 +179,11 @@ ggtitle <- function(label, subtitle = waiver()) {
   labs(title = label, subtitle = subtitle)
 }
 
+#' @rdname labs
+#' @export
+#' @param plot A ggplot object
+#' @description
+#' `get_labs()` retrieves completed labels from a plot.
 get_labs <- function(plot = get_last_plot()) {
   plot <- ggplot_build(plot)
 
diff --git a/man/labs.Rd b/man/labs.Rd
index 6fc7e9aa08..5d6fb93b52 100644
--- a/man/labs.Rd
+++ b/man/labs.Rd
@@ -5,6 +5,7 @@
 \alias{xlab}
 \alias{ylab}
 \alias{ggtitle}
+\alias{get_labs}
 \title{Modify axis, legend, and plot labels}
 \usage{
 labs(
@@ -22,6 +23,8 @@ xlab(label)
 ylab(label)
 
 ggtitle(label, subtitle = waiver())
+
+get_labs(plot = get_last_plot())
 }
 \arguments{
 \item{...}{A list of new name-value pairs. The name should be an aesthetic.}
@@ -44,6 +47,8 @@ rlang \link[rlang:as_function]{lambda} function notation.}
 
 \item{label}{The title of the respective axis (for \code{xlab()} or \code{ylab()}) or
 of the plot (for \code{ggtitle()}).}
+
+\item{plot}{A ggplot object}
 }
 \description{
 Good labels are critical for making your plots accessible to a wider
@@ -52,6 +57,8 @@ variable name. Use the plot \code{title} and \code{subtitle} to explain the
 main findings. It's common to use the \code{caption} to provide information
 about the data source. \code{tag} can be used for adding identification tags
 to differentiate between multiple plots.
+
+\code{get_labs()} retrieves completed labels from a plot.
 }
 \details{
 You can also set axis and legend labels in the individual scales (using