Consistently format superseded functions (#333)

Fixes #308

R/breaks-retired.R

@@ -1,6 +1,8 @@
 #' Regularly spaced dates
 #'
+#' @description
 #' `r lifecycle::badge('superseded')`
+#'
 #' Use `breaks_width()` instead.
 #'
 #' @param width an interval specification, one of "sec", "min", "hour",
@@ -15,7 +17,9 @@ date_breaks <- function(width = "1 month") {
 
 #' Pretty breaks on transformed scale
 #'
+#' @description
 #' `r lifecycle::badge('superseded')`
+#'
 #' These often do not produce very attractive breaks.
 #'
 #' @param trans function of single variable, `x`, that given a numeric
@@ -42,7 +46,9 @@ trans_breaks <- function(trans, inv, n = 5, ...) {
 
 #' Compute breaks for continuous scale
 #'
+#' @description
 #' `r lifecycle::badge('superseded')`
+#'
 #' This function wraps up the components needed to go from a continuous range
 #' to a set of breaks and labels suitable for display on axes or legends.
 #'

R/breaks.r

@@ -103,8 +103,6 @@ extended_breaks <- breaks_extended
 #' primarily useful for date/times, as [extended_breaks()] should do a slightly
 #' better job for numeric scales.
 #'
-#' `pretty_breaks()` is superseded; use `breaks_pretty()` instead.
-#'
 #' @inheritParams breaks_extended
 #' @param ... other arguments passed on to [pretty()]
 #' @export
@@ -130,7 +128,15 @@ breaks_pretty <- function(n = 5, ...) {
   }
 }
 
+#' Superseded interface to `breaks_pretty()`
+#'
+#' @description
+#' `r lifecycle::badge("superseded")`
+#'
+#' These functions are kept for backward compatibility; you should switch
+#' to [breaks_pretty()] for new code.
+#'
+#' @keywords internal
 #' @export
-#' @usage NULL
-#' @rdname breaks_pretty
+#' @inheritParams breaks_pretty
 pretty_breaks <- breaks_pretty

R/label-date.R

@@ -8,10 +8,7 @@
 #' "firsts" (e.g. first day of month, first day of day) specially;
 #' `date_short()` formats changes (e.g. new month, new year) specially.
 #'
-#' @section Old interface:
-#' `date_format()` and `time_format()` are superseded; please use `label_date()`
-#' and `label_time()` instead.
-#' @inherit number_format return
+#' @inherit label_number return
 #' @param format For `date_format()` and `time_format()` a date/time format
 #'   string using standard POSIX specification.  See [strptime()] for details.
 #'
@@ -114,10 +111,19 @@ label_time <- function(format = "%H:%M:%S", tz = "UTC") {
 }
 
 
+#' Superseded interface to `label_date()`/`label_time()`
+#'
+#' @description
+#' `r lifecycle::badge("superseded")`
+#'
+#' These functions are kept for backward compatibility; you should switch
+#' to [label_date()/[label_time()] for new code.
+#'
+#' @keywords internal
 #' @export
-#' @rdname label_date
+#' @inheritParams label_date
 date_format <- label_date
 
 #' @export
-#' @rdname label_date
+#' @rdname date_format
 time_format <- label_time

R/label-dollar.R

@@ -3,11 +3,7 @@
 #' Format numbers as currency, rounding values to dollars or cents using
 #' a convenient heuristic.
 #'
-#' @section Old interface:
-#' `dollar()` and `format_dollar()` are superseded; please use `label_dollar()`
-#' instead.
-#'
-#' @inherit number_format return params
+#' @inherit label_number return params
 #' @param accuracy,largest_with_cents Number to round to. If `NULL`, the default,
 #'   values will be rounded to the nearest integer, unless any of the
 #'   values has non-zero fractional component (e.g. cents) and the largest
@@ -101,12 +97,21 @@ needs_cents <- function(x, threshold) {
   !all(x == floor(x), na.rm = TRUE)
 }
 
+#' Superseded interface to `label_dollar()`
+#'
+#' @description
+#' `r lifecycle::badge("superseded")`
+#'
+#' These functions are kept for backward compatibility; you should switch
+#' to [label_dollar()] for new code.
+#'
+#' @keywords internal
 #' @export
-#' @rdname label_dollar
+#' @inheritParams label_dollar
 dollar_format <- label_dollar
 
 #' @export
-#' @rdname label_dollar
+#' @rdname dollar_format
 #' @param x A numeric vector
 dollar <- function(x, accuracy = NULL, scale = 1, prefix = "$",
                    suffix = "", big.mark = ",", decimal.mark = ".",

R/label-expression.R

@@ -4,10 +4,7 @@
 #' `label_math()` constructs expressions by replacing the pronoun `.x`
 #' with each string.
 #'
-#' @section Old interface:
-#' `parse_format()` and `math_format()` was superseded; please use
-#' `label_parse()` and `label_math()` instead.
-#' @inherit number_format return
+#' @inherit label_number return
 #' @seealso [plotmath] for the details of mathematical formatting in R.
 #' @export
 #' @family labels for continuous scales
@@ -54,10 +51,19 @@ label_math <- function(expr = 10^.x, format = force) {
   }
 }
 
-#' @rdname label_parse
+#' Superseded interface to `label_parse()`/`label_math()`
+#'
+#' @description
+#' `r lifecycle::badge("superseded")`
+#'
+#' These functions are kept for backward compatibility; you should switch
+#' to [label_parse()]/[label_math()] for new code.
+#'
+#' @keywords internal
 #' @export
+#' @inheritParams label_parse
 parse_format <- label_parse
-#' @rdname label_parse
+#' @rdname parse_format
 #' @export
 math_format <- label_math
 

R/label-log.R

@@ -5,7 +5,7 @@
 #' @param base Base of logarithm to use
 #' @param digits Number of significant digits to show for the exponent. Argument
 #'   is passed on to [base::format()].
-#' @inherit number_format return
+#' @inherit label_number return
 #' @seealso [breaks_log()] for the related breaks algorithm.
 #' @export
 #' @family labels for log scales

R/label-number-si.R

@@ -6,7 +6,7 @@
 #' See [Metric Prefix](https://en.wikipedia.org/wiki/Metric_prefix) on Wikipedia
 #' for more details.
 #'
-#' @inherit number_format return params
+#' @inherit label_number return params
 #' @param unit Unit of measurement (e.g. `"m"` for meter, the SI unit of length).
 #' @param scale A scaling factor: `x` will be multiplied by `scale` before
 #'   formatting. This is useful if the underlying data is already using an SI

R/label-number.r

@@ -13,10 +13,7 @@
 #' 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.
-#' @section Old interface:
-#' `number_format()`, `comma_format()`, and `comma()` are superseded; please use
-#' `label_number()` and `label_comma()` instead.
-#' @param x A numeric vector to format.
+#'
 #' @param accuracy A number to round to. Use (e.g.) `0.01` to show 2 decimal
 #'   places of precision. If `NULL`, the default, uses a heuristic that should
 #'   ensure breaks have the minimum number of digits needed to show the
@@ -102,8 +99,18 @@ label_comma <- function(accuracy = NULL, scale = 1, prefix = "",
   )
 }
 
+#' Superseded interface to `label_number()`/`label_comma()`
+#'
+#' @description
+#' `r lifecycle::badge("superseded")`
+#'
+#' These functions are kept for backward compatibility; you should switch
+#' to [label_number()]/[label_comma()] for new code.
+#'
+#' @keywords internal
 #' @export
-#' @rdname label_number
+#' @inheritParams label_number
+#' @param x A numeric vector to format.
 comma <- function(x, accuracy = NULL, scale = 1, prefix = "",
                   suffix = "", big.mark = ",", decimal.mark = ".",
                   trim = TRUE, digits, ...) {
@@ -127,11 +134,11 @@ comma <- function(x, accuracy = NULL, scale = 1, prefix = "",
 }
 
 #' @export
-#' @rdname label_number
+#' @rdname comma
 number_format <- label_number
 
 #' @export
-#' @rdname label_number
+#' @rdname comma
 comma_format <- label_comma
 
 #' A low-level numeric formatter

R/label-ordinal.R

@@ -3,10 +3,7 @@
 #' Round values to integers and then display as ordinal values (e.g. 1st, 2nd,
 #' 3rd). Built-in rules are provided for English, French, and Spanish.
 #'
-#' @section Old interface:
-#' `ordinal()` and `format_ordinal()` are superseded; please use `label_ordinal()`
-#' instead.
-#' @inherit number_format return params
+#' @inherit label_number return params
 #' @param prefix,suffix Symbols to display before and after value.
 #' @param rules Named list of regular expressions, matched in order.
 #'   Name gives suffix, and value specifies which numbers to match.
@@ -83,12 +80,21 @@ ordinal_spanish <- function() {
   stats::setNames(list("."), ".\u00ba")
 }
 
+#' Superseded interface to `label_ordinal()`
+#'
+#' @description
+#' `r lifecycle::badge("superseded")`
+#'
+#' These functions are kept for backward compatibility; you should switch
+#' to [label_ordinal()] for new code.
+#'
+#' @keywords internal
 #' @export
-#' @rdname label_ordinal
+#' @inheritParams label_ordinal
 ordinal_format <- label_ordinal
 
 #' @export
-#' @rdname label_ordinal
+#' @rdname ordinal_format
 ordinal <- function(x, prefix = "", suffix = "", big.mark = " ",
                     rules = ordinal_english(), ...) {
   na_idx <- is.na(x)

R/label-percent.R

@@ -1,9 +1,6 @@
 #' Label percentages (2.5%, 50%, etc)
 #'
-#' @section Old interface:
-#' `percent()` and `percent_format()` are superseded; please use `label_percent()`
-#' instead.
-#' @inherit number_format return params
+#' @inherit label_number return params
 #' @export
 #' @family labels for continuous scales
 #' @examples
@@ -31,12 +28,21 @@ label_percent <- function(accuracy = NULL, scale = 100, prefix = "",
   )
 }
 
+#' Superseded interface to `label_percent()`
+#'
+#' @description
+#' `r lifecycle::badge("superseded")`
+#'
+#' These functions are kept for backward compatibility; you should switch
+#' to [label_percent()] for new code.
+#'
+#' @keywords internal
 #' @export
-#' @rdname label_percent
+#' @inheritParams label_percent
 percent_format <- label_percent
 
 #' @export
-#' @rdname label_percent
+#' @rdname percent_format
 percent <- function(x, accuracy = NULL, scale = 100, prefix = "",
                     suffix = "%", big.mark = " ", decimal.mark = ".",
                     trim = TRUE, ...) {

R/label-pvalue.R

@@ -2,10 +2,7 @@
 #'
 #' Formatter for p-values, using "<" and ">" for p-values close to 0 and 1.
 #'
-#' @section Old interface:
-#' `pvalue()` and `pvalue_format()` are superseded; please use `label_pvalue()`
-#' instead.
-#' @inherit number_format return params
+#' @inherit label_number return params
 #' @param prefix A character vector of length 3 giving the prefixes to
 #'   put in front of numbers. The default values are `c("<", "", ">")`
 #'   if `add_p` is `TRUE` and `c("p<", "p=", "p>")` if `FALSE`.
@@ -34,11 +31,21 @@ label_pvalue <- function(accuracy = .001, decimal.mark = ".", prefix = NULL, add
   }
 }
 
-#' @rdname label_pvalue
+#' Superseded interface to `label_pvalue()`
+#'
+#' @description
+#' `r lifecycle::badge("superseded")`
+#'
+#' These functions are kept for backward compatibility; you should switch
+#' to [label_pvalue()] for new code.
+#'
+#' @keywords internal
+#' @export
+#' @inheritParams label_pvalue
 #' @export
 pvalue_format <- label_pvalue
 
-#' @rdname label_pvalue
+#' @rdname pvalue_format
 #' @export
 pvalue <- function(x,
                    accuracy = .001,

R/label-scientific.R

@@ -1,9 +1,6 @@
 #' Label numbers with scientific notation (e.g. 1e05, 1.5e-02)
 #'
-#' @section Old interface:
-#' `scientific_format()` and `scientific()` are superseded; please use
-#' `label_scientific()`.
-#' @inherit number_format return params
+#' @inherit label_number return params
 #' @param digits Number of digits to show before exponent.
 #' @param prefix,suffix Symbols to display before and after value.
 #' @param ... Other arguments passed on to [base::format()].
@@ -32,12 +29,21 @@ label_scientific <- function(digits = 3, scale = 1, prefix = "", suffix = "",
   }
 }
 
+#' Superseded interface to `label_scientific()`
+#'
+#' @description
+#' `r lifecycle::badge("superseded")`
+#'
+#' These functions are kept for backward compatibility; you should switch
+#' to [label_scientific()] for new code.
+#'
+#' @keywords internal
 #' @export
-#' @rdname label_scientific
+#' @inheritParams label_scientific
 scientific_format <- label_scientific
 
 #' @export
-#' @rdname label_scientific
+#' @rdname scientific_format
 scientific <- function(x, digits = 3, scale = 1, prefix = "", suffix = "",
                        decimal.mark = ".", trim = TRUE, ...) {
   if (length(x) == 0) {

R/label-wrap.R

@@ -2,9 +2,7 @@
 #'
 #' Uses [strwrap()] to split long labels across multiple lines.
 #'
-#' @section Old interface:
-#' `wrap_format()` is superseded; please use `label_format()` instead.
-#' @inherit number_format return
+#' @inherit label_number return
 #' @param width Number of characters per line.
 #' @export
 #' @family labels for discrete scales
@@ -24,6 +22,15 @@ label_wrap <- function(width) {
   }
 }
 
+#' Superseded interface to `label_wrap()`
+#'
+#' @description
+#' `r lifecycle::badge("superseded")`
+#'
+#' These functions are kept for backward compatibility; you should switch
+#' to [label_wrap()] for new code.
+#'
+#' @keywords internal
 #' @export
-#' @rdname label_wrap
+#' @inheritParams label_wrap
 wrap_format <- label_wrap