Fix #431 - improve on the consistency of return documentation for lab…

…el and breaks functions

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

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

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

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

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

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) {

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

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

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

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