From 4a95f277767e29b080eb0c4e815e360cdbf983fd Mon Sep 17 00:00:00 2001
From: Thomas Lin Pedersen <thomasp85@gmail.com>
Date: Fri, 25 Oct 2024 15:00:26 +0200
Subject: [PATCH] Fix #431 - improve on the consistency of return documentation
 for label and breaks functions

---
 R/breaks-log.R           |  4 ++++
 R/breaks.R               | 19 +++++++++++++++++++
 R/label-bytes.R          |  4 ++--
 R/label-compose.R        |  4 +---
 R/label-currency.R       |  1 +
 R/label-date.R           |  1 +
 R/label-dictionary.R     |  3 +--
 R/label-glue.R           |  4 +---
 R/label-log.R            |  4 ++--
 R/label-number-auto.R    |  2 ++
 man/breaks_exp.Rd        |  6 ++++++
 man/breaks_extended.Rd   |  6 ++++++
 man/breaks_log.Rd        |  6 ++++++
 man/breaks_pretty.Rd     |  6 ++++++
 man/breaks_timespan.Rd   |  6 ++++++
 man/breaks_width.Rd      |  6 ++++++
 man/compose_label.Rd     | 10 ++++++++--
 man/label_bytes.Rd       | 10 ++++++++--
 man/label_dictionary.Rd  | 10 ++++++++--
 man/label_glue.Rd        | 10 ++++++++--
 man/label_number_auto.Rd | 10 ++++++++++
 21 files changed, 112 insertions(+), 20 deletions(-)

diff --git a/R/breaks-log.R b/R/breaks-log.R
index cbfe7cfc..168dd2b0 100644
--- a/R/breaks-log.R
+++ b/R/breaks-log.R
@@ -25,6 +25,9 @@
 #' breaks, `>= n-2`, are returned or all candidates have been used.
 #' @param n desired number of breaks
 #' @param base base of logarithm to use
+#'
+#' @inherit breaks_width return
+#'
 #' @export
 #' @examples
 #' demo_log10(c(1, 1e5))
@@ -93,6 +96,7 @@ log_breaks <- breaks_log
 #'   negative numbers.
 #'
 #' @return A function to generate minor ticks.
+#'
 #' @export
 #'
 #' @examples
diff --git a/R/breaks.R b/R/breaks.R
index adf194d2..09cf1381 100644
--- a/R/breaks.R
+++ b/R/breaks.R
@@ -16,6 +16,13 @@
 #'   offset by three months and five days, which is useful for the UK tax year.
 #'   Note that due to way that dates are rounded, there's no guarantee that
 #'   `offset = c(x, y)` will give the same result as `offset = c(y, x)`.
+#'
+#' @return
+#' All `breaks_()` functions return a function for generating breaks. These
+#' functions takes, as their first argument a vector of values that represent
+#' the data range to provide breaks for. Some will optionally take a second
+#' argument that allows you to specify the number of breaks to recieve.
+#'
 #' @export
 #' @examples
 #' demo_continuous(c(0, 100))
@@ -71,6 +78,9 @@ breaks_width <- function(width, offset = 0) {
 #' @param n Desired number of breaks. You may get slightly more or fewer
 #'   breaks that requested.
 #' @param ... other arguments passed on to [labeling::extended()]
+#'
+#' @inherit breaks_width return
+#'
 #' @references Talbot, J., Lin, S., Hanrahan, P. (2010) An Extension of
 #'  Wilkinson's Algorithm for Positioning Tick Labels on Axes, InfoVis
 #'  2010 <http://vis.stanford.edu/files/2010-TickLabels-InfoVis.pdf>.
@@ -105,6 +115,9 @@ extended_breaks <- breaks_extended
 #'
 #' @inheritParams breaks_extended
 #' @param ... other arguments passed on to [pretty()]
+#'
+#' @inherit breaks_width return
+#'
 #' @export
 #' @examples
 #' one_month <- as.POSIXct(c("2020-05-01", "2020-06-01"))
@@ -151,6 +164,9 @@ pretty_breaks <- breaks_pretty
 #' determines the base used for calculating breaks
 #'
 #' @param unit The unit used to interpret numeric data input
+#'
+#' @inherit breaks_width return
+#'
 #' @inheritParams breaks_extended
 #' @export
 #' @examples
@@ -193,6 +209,9 @@ breaks_timespan <- function(unit = c("secs", "mins", "hours", "days", "weeks"),
 #' uses [`breaks_extended()`].
 #'
 #' @inheritParams breaks_extended
+#'
+#' @inherit breaks_width return
+#' 
 #' @export
 #' @examples
 #' # Small range
diff --git a/R/label-bytes.R b/R/label-bytes.R
index 1eb90ef4..f142bac7 100644
--- a/R/label-bytes.R
+++ b/R/label-bytes.R
@@ -5,6 +5,7 @@
 #' [Units of Information](https://en.wikipedia.org/wiki/Units_of_information)
 #' on Wikipedia for more details.
 #'
+#' @inherit label_number return
 #' @param units Unit to use. Should either one of:
 #'   * "kB", "MB", "GB", "TB", "PB", "EB", "ZB", and "YB" for
 #'     SI units (base 1000).
@@ -14,8 +15,7 @@
 #'     unit for each value.
 #' @inheritParams number_format
 #' @inheritDotParams number
-#' @return A labeller function that takes a numeric vector of breaks and
-#'   returns a character vector of labels.
+#'
 #' @export
 #' @family labels for continuous scales
 #' @family labels for log scales
diff --git a/R/label-compose.R b/R/label-compose.R
index d324c069..953aa2b9 100644
--- a/R/label-compose.R
+++ b/R/label-compose.R
@@ -3,14 +3,12 @@
 #' This labeller provides a general mechanism for composing two or more
 #' labellers together.
 #'
+#' @inherit label_number return
 #' @param ... One or more labelling functions. These will be applied to breaks
 #'   consecutively.
 #'   [Lambda syntax][rlang::as_function] is allowed.
 #' @param call A call to display in error messages.
 #'
-#' @return A labelling function that applies the provided
-#'   functions to breaks to return labels.
-#'
 #' @export
 #'
 #' @examples
diff --git a/R/label-currency.R b/R/label-currency.R
index 98d18e3d..7496a82f 100644
--- a/R/label-currency.R
+++ b/R/label-currency.R
@@ -10,6 +10,7 @@
 #'   the largest value is less than `largest_with_fractional` which by default
 #'   is 100,000.
 #' @param prefix,suffix Symbols to display before and after value.
+#'
 #' @inheritDotParams number
 #' @export
 #' @family labels for continuous scales
diff --git a/R/label-date.R b/R/label-date.R
index 0cf47a41..31188521 100644
--- a/R/label-date.R
+++ b/R/label-date.R
@@ -24,6 +24,7 @@
 #'   [stringi::stri_locale_list()].
 #' @param leading A string to replace leading zeroes with. Can be `""` to
 #'   disable leading characters or `"\u2007"` for figure-spaces.
+#'
 #' @export
 #' @examples
 #' date_range <- function(start, days) {
diff --git a/R/label-dictionary.R b/R/label-dictionary.R
index 15dd12e1..bd5a787e 100644
--- a/R/label-dictionary.R
+++ b/R/label-dictionary.R
@@ -4,14 +4,13 @@
 #' Use `label_dictionary()` for looking up succinct breaks in a named character
 #' vector giving complete labels.
 #'
+#' @inherit label_number return
 #' @param dictionary A named character vector of labels. The names are expected
 #'   to match the breaks, and the values become the labels.
 #' @param nomatch A string to label breaks that do not match any name in
 #'  `dictionary`. When `NULL` (default), the breaks are not translated but are
 #'  kept as-is.
 #'
-#' @return A labeller function that takes a character vector of breaks and
-#'   returns a character vector of labels.
 #' @export
 #' @family labels for discrete scales
 #' @examples
diff --git a/R/label-glue.R b/R/label-glue.R
index 156d4be9..f1764eba 100644
--- a/R/label-glue.R
+++ b/R/label-glue.R
@@ -3,14 +3,12 @@
 #' Use `label_glue()` to perform string interpolation using the \pkg{glue}
 #' package. Enclosed expressions will be evaluated as R code.
 #'
+#' @inherit label_number return
 #' @param pattern A glue string used for formatting. The `x` variable holds the
 #'   breaks, so that `"{x}"` (default) returns the breaks as-is.
 #' @param ... Arguments passed on to [`glue::glue()`].
 #' @param parse Whether to return labels as expressions.
 #' @inheritParams glue::glue
-#'
-#' @return A labeller function that takes a vector of breaks and returns a
-#'   character vector of labels.
 #' @export
 #' @family labels for continuous scales
 #' @family labels for discrete scales
diff --git a/R/label-log.R b/R/label-log.R
index e31e2bb8..1607f440 100644
--- a/R/label-log.R
+++ b/R/label-log.R
@@ -4,7 +4,7 @@
 #' superscript formatting. `label_log()` returns expressions suitable for
 #' labelling in scales, whereas `format_log()` returns deparsed text.
 #'
-#'
+#' @inherit label_number return
 #' @param x A numeric vector to format
 #' @param base Base of logarithm to use
 #' @param digits Number of significant digits to show for the exponent. Argument
@@ -13,7 +13,7 @@
 #'   default, `NULL`, displays signs if there are zeroes or negative numbers
 #'   present.
 #' @param ... Passed on to `format()`.
-#' @inherit label_number return
+#' 
 #' @seealso [breaks_log()] for the related breaks algorithm.
 #' @export
 #' @family labels for log scales
diff --git a/R/label-number-auto.R b/R/label-number-auto.R
index d8b47ea9..a3f19dd8 100644
--- a/R/label-number-auto.R
+++ b/R/label-number-auto.R
@@ -4,6 +4,8 @@
 #' heuristics designed to automatically generate useful labels across a wide
 #' range of inputs
 #'
+#' @inherit label_number return
+#'
 #' @export
 #' @family labels for continuous scales
 #' @examples
diff --git a/man/breaks_exp.Rd b/man/breaks_exp.Rd
index 536b4412..f90a9fd4 100644
--- a/man/breaks_exp.Rd
+++ b/man/breaks_exp.Rd
@@ -12,6 +12,12 @@ breaks that requested.}
 
 \item{...}{other arguments passed on to \code{\link[labeling:extended]{labeling::extended()}}}
 }
+\value{
+All \code{breaks_()} functions return a function for generating breaks. These
+functions takes, as their first argument a vector of values that represent
+the data range to provide breaks for. Some will optionally take a second
+argument that allows you to specify the number of breaks to recieve.
+}
 \description{
 This breaks function typically labels zero and the last \code{n - 1} integers of a
 range if that range is large enough (currently: 3). For smaller ranges, it
diff --git a/man/breaks_extended.Rd b/man/breaks_extended.Rd
index 6e268749..15bcb68b 100644
--- a/man/breaks_extended.Rd
+++ b/man/breaks_extended.Rd
@@ -13,6 +13,12 @@ breaks that requested.}
 
 \item{...}{other arguments passed on to \code{\link[labeling:extended]{labeling::extended()}}}
 }
+\value{
+All \code{breaks_()} functions return a function for generating breaks. These
+functions takes, as their first argument a vector of values that represent
+the data range to provide breaks for. Some will optionally take a second
+argument that allows you to specify the number of breaks to recieve.
+}
 \description{
 Uses Wilkinson's extended breaks algorithm as implemented in the
 \pkg{labeling} package.
diff --git a/man/breaks_log.Rd b/man/breaks_log.Rd
index 940f5a25..ea28d2f9 100644
--- a/man/breaks_log.Rd
+++ b/man/breaks_log.Rd
@@ -12,6 +12,12 @@ breaks_log(n = 5, base = 10)
 
 \item{base}{base of logarithm to use}
 }
+\value{
+All \code{breaks_()} functions return a function for generating breaks. These
+functions takes, as their first argument a vector of values that represent
+the data range to provide breaks for. Some will optionally take a second
+argument that allows you to specify the number of breaks to recieve.
+}
 \description{
 This algorithm starts by looking for integer powers of \code{base}. If that
 doesn't provide enough breaks, it then looks for additional intermediate
diff --git a/man/breaks_pretty.Rd b/man/breaks_pretty.Rd
index 0f4a5c6e..c1b46802 100644
--- a/man/breaks_pretty.Rd
+++ b/man/breaks_pretty.Rd
@@ -12,6 +12,12 @@ breaks that requested.}
 
 \item{...}{other arguments passed on to \code{\link[=pretty]{pretty()}}}
 }
+\value{
+All \code{breaks_()} functions return a function for generating breaks. These
+functions takes, as their first argument a vector of values that represent
+the data range to provide breaks for. Some will optionally take a second
+argument that allows you to specify the number of breaks to recieve.
+}
 \description{
 Uses default R break algorithm as implemented in \code{\link[=pretty]{pretty()}}. This is
 primarily useful for date/times, as \code{\link[=extended_breaks]{extended_breaks()}} should do a slightly
diff --git a/man/breaks_timespan.Rd b/man/breaks_timespan.Rd
index dc750729..8ca4b61c 100644
--- a/man/breaks_timespan.Rd
+++ b/man/breaks_timespan.Rd
@@ -12,6 +12,12 @@ breaks_timespan(unit = c("secs", "mins", "hours", "days", "weeks"), n = 5)
 \item{n}{Desired number of breaks. You may get slightly more or fewer
 breaks that requested.}
 }
+\value{
+All \code{breaks_()} functions return a function for generating breaks. These
+functions takes, as their first argument a vector of values that represent
+the data range to provide breaks for. Some will optionally take a second
+argument that allows you to specify the number of breaks to recieve.
+}
 \description{
 As timespan units span a variety of bases (1000 below seconds, 60 for second
 and minutes, 24 for hours, and 7 for days), the range of the input data
diff --git a/man/breaks_width.Rd b/man/breaks_width.Rd
index 362df4b0..880d04f6 100644
--- a/man/breaks_width.Rd
+++ b/man/breaks_width.Rd
@@ -23,6 +23,12 @@ offset by three months and five days, which is useful for the UK tax year.
 Note that due to way that dates are rounded, there's no guarantee that
 \code{offset = c(x, y)} will give the same result as \code{offset = c(y, x)}.}
 }
+\value{
+All \code{breaks_()} functions return a function for generating breaks. These
+functions takes, as their first argument a vector of values that represent
+the data range to provide breaks for. Some will optionally take a second
+argument that allows you to specify the number of breaks to recieve.
+}
 \description{
 Useful for numeric, date, and date-time scales.
 }
diff --git a/man/compose_label.Rd b/man/compose_label.Rd
index a9950860..956d755f 100644
--- a/man/compose_label.Rd
+++ b/man/compose_label.Rd
@@ -14,8 +14,14 @@ consecutively.
 \item{call}{A call to display in error messages.}
 }
 \value{
-A labelling function that applies the provided
-functions to breaks to return labels.
+All \code{label_()} functions return a "labelling" function, i.e. a function that
+takes a vector \code{x} and returns a character vector of \code{length(x)} giving a
+label for each input value.
+
+Labelling functions are designed to be used with the \code{labels} argument of
+ggplot2 scales. The examples demonstrate their use with x scales, but
+they work similarly for all scales, including those that generate legends
+rather than axes.
 }
 \description{
 This labeller provides a general mechanism for composing two or more
diff --git a/man/label_bytes.Rd b/man/label_bytes.Rd
index 25514532..4e0b77da 100644
--- a/man/label_bytes.Rd
+++ b/man/label_bytes.Rd
@@ -84,8 +84,14 @@ width (see \code{\link[base:format]{base::format()}}).}
   }}
 }
 \value{
-A labeller function that takes a numeric vector of breaks and
-returns a character vector of labels.
+All \code{label_()} functions return a "labelling" function, i.e. a function that
+takes a vector \code{x} and returns a character vector of \code{length(x)} giving a
+label for each input value.
+
+Labelling functions are designed to be used with the \code{labels} argument of
+ggplot2 scales. The examples demonstrate their use with x scales, but
+they work similarly for all scales, including those that generate legends
+rather than axes.
 }
 \description{
 Scale bytes into human friendly units. Can use either SI units (e.g.
diff --git a/man/label_dictionary.Rd b/man/label_dictionary.Rd
index 7731c13a..49c59053 100644
--- a/man/label_dictionary.Rd
+++ b/man/label_dictionary.Rd
@@ -15,8 +15,14 @@ to match the breaks, and the values become the labels.}
 kept as-is.}
 }
 \value{
-A labeller function that takes a character vector of breaks and
-returns a character vector of labels.
+All \code{label_()} functions return a "labelling" function, i.e. a function that
+takes a vector \code{x} and returns a character vector of \code{length(x)} giving a
+label for each input value.
+
+Labelling functions are designed to be used with the \code{labels} argument of
+ggplot2 scales. The examples demonstrate their use with x scales, but
+they work similarly for all scales, including those that generate legends
+rather than axes.
 }
 \description{
 Use \code{label_dictionary()} for looking up succinct breaks in a named character
diff --git a/man/label_glue.Rd b/man/label_glue.Rd
index f4001974..3ead7735 100644
--- a/man/label_glue.Rd
+++ b/man/label_glue.Rd
@@ -19,8 +19,14 @@ evaluated from left to right. If \code{.x} is an environment, the expressions ar
 evaluated in that environment and \code{.envir} is ignored. If \code{NULL} is passed, it is equivalent to \code{\link[=emptyenv]{emptyenv()}}.}
 }
 \value{
-A labeller function that takes a vector of breaks and returns a
-character vector of labels.
+All \code{label_()} functions return a "labelling" function, i.e. a function that
+takes a vector \code{x} and returns a character vector of \code{length(x)} giving a
+label for each input value.
+
+Labelling functions are designed to be used with the \code{labels} argument of
+ggplot2 scales. The examples demonstrate their use with x scales, but
+they work similarly for all scales, including those that generate legends
+rather than axes.
 }
 \description{
 Use \code{label_glue()} to perform string interpolation using the \pkg{glue}
diff --git a/man/label_number_auto.Rd b/man/label_number_auto.Rd
index 401c72dc..0aeac3a1 100644
--- a/man/label_number_auto.Rd
+++ b/man/label_number_auto.Rd
@@ -6,6 +6,16 @@
 \usage{
 label_number_auto()
 }
+\value{
+All \code{label_()} functions return a "labelling" function, i.e. a function that
+takes a vector \code{x} and returns a character vector of \code{length(x)} giving a
+label for each input value.
+
+Labelling functions are designed to be used with the \code{labels} argument of
+ggplot2 scales. The examples demonstrate their use with x scales, but
+they work similarly for all scales, including those that generate legends
+rather than axes.
+}
 \description{
 Switches between \code{\link[=number_format]{number_format()}} and \code{\link[=scientific_format]{scientific_format()}} based on a set of
 heuristics designed to automatically generate useful labels across a wide