Merge pull request #1694 from olivroy/error-msg-follow

Refactor documentation and test nomenclature

R/data_color.R

@@ -26,8 +26,8 @@
 #'
 #' @description
 #'
-#' It's possible to add color to data cells according to their values with the
-#' `data_color()` function. There is a multitude of ways to perform data cell
+#' It's possible to add color to data cells according to their values with
+#' `data_color()` There is a multitude of ways to perform data cell
 #' colorizing here:
 #'
 #' - targeting: we can constrain which columns and rows should receive the
@@ -41,9 +41,8 @@
 #' argument controls this through keywords and other arguments act as inputs to
 #' specific methods
 #' - coloring function: a custom function can be supplied to the `fn` argument
-#' for finer control over color evaluation with data; the color mapping
-#' `col_*()` functions in the **scales** package can be used here or any
-#' function you might want to define
+#' for finer control over color evaluation with data; the `scales::col_*()`
+#' color mapping functions can be used here or any function you might want to define
 #' - color palettes: with `palette` we could supply a vector of colors, a
 #' **virdis** or **RColorBrewer** palette name, or, a palette from the
 #' **paletteer** package
@@ -60,7 +59,7 @@
 #' automatically recolor the foreground text to provide the best contrast (can
 #' be deactivated with `autocolor_text = FALSE`)
 #'
-#' The `data_color()` function won't fail with the default options used, but
+#' `data_color()` won't fail with the default options used, but
 #' that won't typically provide you the type of colorization you really need.
 #' You can however safely iterate through a collection of different options
 #' without running into too many errors.
@@ -207,10 +206,9 @@
 #'
 #'   A color-mapping function. The function should be able to take a vector of
 #'   data values as input and return an equal-length vector of color values. The
-#'   `col_*()` functions provided in the **scales** package (i.e.,
-#'   [scales::col_numeric()], [scales::col_bin()], and [scales::col_factor()])
-#'   can be invoked here with options, as those functions themselves return a
-#'   color-mapping function.
+#'   `scales::col_*()` functions (i.e.,[scales::col_numeric()],
+#'   [scales::col_bin()], and [scales::col_factor()]) can be invoked here with
+#'   options, as those functions themselves return a color-mapping function.
 #'
 #' @param apply_to *How to apply color*
 #'
@@ -284,7 +282,7 @@
 #'
 #' @section Color computation methods:
 #'
-#' The `data_color()` function offers four distinct methods for computing color
+#' `data_color()` offers four distinct methods for computing color
 #' based on cell data values. They are set by the `method` argument and the
 #' options go by the keywords `"numeric"`, `"bin"`, `"quantile"`, and
 #' `"factor"`. There are other arguments in `data_color()` that variously
@@ -295,36 +293,36 @@
 #' ### `"numeric"`
 #'
 #' The `"numeric"` method provides a simple linear mapping from continuous
-#' numeric data to an interpolated `palette`. Internally, this uses the
-#' [scales::col_numeric()] function. This method is suited for numeric data cell
+#' numeric data to an interpolated `palette`. Internally, this uses
+#' [scales::col_numeric()]. This method is suited for numeric data cell
 #' values and can make use of a supplied `domain` value, in the form of a
 #' two-element numeric vector describing the range of values, if provided.
 #'
 #' ### `"bin"`
 #'
 #' The `"bin"` method provides a mapping of continuous numeric data to
-#' value-based bins. Internally, this uses the [scales::col_bin()] function
-#' which itself uses [base::cut()]. As with the `"numeric"` method, `"bin"` is
-#' meant for numeric data cell values. The use of a `domain` value is supported
-#' with this method. The `bins` argument in `data_color()` is specific to this
-#' method, offering the ability to: (1) specify the number of bins, or (2)
-#' provide a vector of cut points.
+#' value-based bins. Internally, this uses [scales::col_bin()] which itself
+#' uses [base::cut()]. As with the `"numeric"` method, `"bin"` is meant for
+#' numeric data cell values. The use of a `domain` value is supported with this
+#' method. The `bins` argument in `data_color()` is specific to this method,
+#' offering the ability to: (1) specify the number of bins, or (2) provide a
+#' vector of cut points.
 #'
 #' ### `"quantile"`
 #'
 #' The `"quantile"` method provides a mapping of continuous numeric data to
-#' quantiles. Internally, this uses the [scales::col_quantile()] function which
-#' itself uses [stats::quantile()]. Input data cell values should be numeric, as
-#' with the `"numeric"` and `"bin"` methods. A numeric `domain` value is
-#' supported with this method. The `quantiles` argument in `data_color()`
-#' controls the number of equal-size quantiles to use.
+#' quantiles. Internally, this uses [scales::col_quantile()] which itself uses
+#' [stats::quantile()]. Input data cell values should be numeric, as with the
+#' `"numeric"` and `"bin"` methods. A numeric `domain` value is supported with
+#' this method. The `quantiles` argument in `data_color()` controls the number
+#' of equal-size quantiles to use.
 #'
 #' ### `"factor"`
 #'
 #' The `"factor"` method provides a mapping of factors to colors. With discrete
 #' palettes, color interpolation is used when the number of factors does not
-#' match the number of colors in the palette. Internally, this uses the
-#' [scales::col_factor()] function. Input data cell values can be of any type
+#' match the number of colors in the palette. Internally, this uses
+#' [scales::col_factor()]. Input data cell values can be of any type
 #' (i.e., factor, character, numeric values, and more are supported). The
 #' optional input to `domain` should take the form of categorical data. The
 #' `levels` and `ordered` arguments in `data_color()` support this method.
@@ -406,7 +404,7 @@
 #'
 #' @section Examples:
 #'
-#' The `data_color()` function can be used without any supplied arguments to
+#' `data_color()` can be used without any supplied arguments to
 #' colorize a **gt** table. Let's do this with the [`exibble`] dataset:
 #'
 #' ```r
@@ -522,11 +520,11 @@
 #' }}
 #'
 #' Using your own function in `fn` can be very useful if you want to make use of
-#' specialized arguments in the **scales** `col_*()` functions. You could even
+#' specialized arguments in the `scales::col_*()` functions. You could even
 #' supply your own specialized function for performing complex colorizing
 #' treatments!
 #'
-#' The `data_color()` function has a way to apply colorization indirectly to
+#' `data_color()` has a way to apply colorization indirectly to
 #' other columns. That is, you can apply colors to a column different from the
 #' one used to generate those specific colors. The trick is to use the
 #' `target_columns` argument. Let's do this with a more complete
@@ -602,7 +600,7 @@
 #'
 #' Now, it's time to use [`pizzaplace`] to create a **gt** table. The color
 #' palette to be used is the `"ggsci::red_material"` one (it's in the **ggsci**
-#' R package but also obtainable from the the **paletteer** package).
+#' R package but also obtainable from the **paletteer** package).
 #' Colorization will be applied to the to the `sold` and `income` columns. We
 #' don't have to specify those in `columns` because those are the only columns
 #' in the table. Also, the `domain` is not set here. We'll use the bounds of the
@@ -727,15 +725,11 @@ data_color <- function(
   na_color <- na_color %||% "#808080"
 
   # Error early if `palette = NA`, or is a numeric vector.
-  if (length(palette) > 0 && (is.numeric(palette) || anyNA(palette))) {
+  if (length(palette) > 0L && (is.numeric(palette) || anyNA(palette))) {
     cli::cli_abort(c(
-      "`palette` must {.help [a valid palette](gt::data_color)}, not a numeric vector."
+      "`palette` must be a {.help [valid palette](gt::data_color)}, not a numeric vector."
     ))
   }
-  # "#FA9DFE"
-  # if (is.character(palette) && length(palette) > 1) {
-  #   check_named_colors(palette[!grepl("#", palette, fixed = TRUE)])
-  # }
 
   # Defuse any function supplied to `fn`; if a function is supplied to `colors`
   # (previous argument for this purpose) then let that take precedent and
@@ -948,7 +942,7 @@ data_color <- function(
 
       # For the "auto" method, we are getting data values in a piece-wise
       # fashion and the strategy is to generate a color function (using
-      # a `col_*()` function from scales) for each piece of data; we can
+      # a `scales::col_*()` function) for each piece of data; we can
       # process vectors that are numeric with `scales::col_numeric()` and
       # vectors that are either character or factor with `scales::col_factor()`
 
@@ -1240,10 +1234,10 @@ screen_palette_for_col_factor <- function(palette, data_vals) {
 #' Are color values in rgba() format?
 #'
 #' The input for this is a character vector that should contain color strings.
-#' While users won't directly supply colors in rgba() format, the `html_color()`
-#' function can produce these types of color values and this utility function is
+#' While users won't directly supply colors in rgba() format, `html_color()`
+#' can produce these types of color values and this utility function is
 #' used in `rgba_to_hex()` to help convert colors *back* to hexadecimal
-#' (ultimately for the `ideal_fgnd_color()` function). The output of
+#' (ultimately for `ideal_fgnd_color()`). The output of
 #' `is_rgba_col()` is a vector of logical values (the same length as the input
 #' `colors` vector).
 #'
@@ -1426,7 +1420,7 @@ html_color <- function(colors, alpha = NULL, call = rlang::caller_env()) {
 
     if (any(is_css_excl_named)) {
 
-      # The `css_exclusive_colors()` function returns a named vector
+      # `css_exclusive_colors()` returns a named vector
       # of the CSS colors not in the X11/R set; the names are the hexadecimal
       # color values
       colors[is_css_excl_named] <-

R/dt_heading.R

@@ -74,7 +74,7 @@ dt_heading_has_subtitle <- function(data) {
 
   heading <- dt_heading_get(data = data)
 
-  length(heading) > 0 && is_nonempty_string(heading$subtitle)
+  length(heading) > 0 && is_nonempty_chr(heading$subtitle)
 }
 
 dt_heading_has_preheader <- function(data) {

R/dt_stub_df.R

@@ -97,7 +97,7 @@ dt_stub_df_init <- function(
       #
       # Ensure that the `row_group_ids` values are simplified to reduce
       # special characters; this requires use of the recoding so that the
-      # generated IDs map correctly to the the supplied labels
+      # generated IDs map correctly to the supplied labels
       #
 
       unique_row_group_labels <- unique(row_group_labels)

R/export.R

@@ -26,7 +26,7 @@
 #'
 #' @description
 #'
-#' The `gtsave()` function makes it easy to save a **gt** table to a file. The
+#' `gtsave()` makes it easy to save a **gt** table to a file. The
 #' function guesses the file type by the extension provided in the output
 #' filename, producing either an HTML, PDF, PNG, LaTeX, or RTF file.
 #'
@@ -543,13 +543,13 @@ gtsave_filename <- function(path, filename) {
 #'
 #' Use a subset of the [`gtcars`] dataset to create a **gt** table. Add a header
 #' with [tab_header()] and then export the table as HTML code with inlined CSS
-#' styles using the `as_raw_html()` function.
+#' styles using `as_raw_html()`.
 #'
 #' ```r
 #' tab_html <-
 #'   gtcars |>
 #'   dplyr::select(mfr, model, msrp) |>
-#'   dplyr::slice(1:5) |>
+#'   dplyr::slice_head(n = 5) |>
 #'   gt() |>
 #'   tab_header(
 #'     title = md("Data listing from **gtcars**"),
@@ -923,8 +923,8 @@ as_rtf <- function(
 #' @section Examples:
 #'
 #' Use a subset of the [`gtcars`] dataset to create a **gt** table. Add a header
-#' with [tab_header()] and then export the table as OOXML code for Word using the
-#' `as_word()` function.
+#' with [tab_header()] and then export the table as OOXML code for Word using
+#' `as_word()`
 #'
 #' ```r
 #' tab_rtf <-
@@ -1146,8 +1146,8 @@ as_word_tbl_body <- function(
 #'
 #' @description
 #'
-#' The `as_gtable()` function performs the transformation of a `gt_tbl` object
-#' to a `gtable` object.
+#' `as_gtable()` performs the transformation of a `gt_tbl` object to a
+#' [`gtable`][gtable::gtable()] object.
 #'
 #' @inheritParams gtsave
 #'
@@ -1501,10 +1501,10 @@ grid_layout_widths <- function(layout, data) {
 #' @description
 #'
 #' We can extract the body of a **gt** table, even at various stages of its
-#' rendering, from a `gt_tbl` object using the `extract_body()` function. By
-#' default, the data frame returned will have gone through all of the build
-#' stages but we can intercept the table body after a certain build stage.
-#' Here are the eight different build stages and some notes about each:
+#' rendering, from a `gt_tbl` object using `extract_body()`. By default, the
+#' data frame returned will have gone through all of the build stages but we
+#' can intercept the table body after a certain build stage. Here are the eight
+#' different build stages and some notes about each:
 #'
 #' 1. `"init"`: the body table is initialized here, entirely with `NA` values.
 #' It's important to note that all columns of the are of the `character` type in
@@ -1525,7 +1525,7 @@ grid_layout_widths <- function(layout, data) {
 #' values now become the string `"NA"`, so, there aren't any true missing values
 #' in this body table.
 #'
-#' 5. `"cols_merged"`: The result of column-merging operations (though
+#' 5. `"cols_merged"`: The result of column-merging operations (through
 #' [cols_merge()] and related functions) is materialized here. Columns that were
 #' asked to be hidden will be present here (i.e., hiding columns doesn't remove
 #' them from the body table).
@@ -1658,9 +1658,9 @@ extract_body <- function(
 #' @description
 #'
 #' Get a list of summary row data frames from a `gt_tbl` object where summary
-#' rows were added via the [summary_rows()] function. The output data frames
-#' contain the `group_id` and `rowname` columns, whereby `rowname` contains
-#' descriptive stub labels for the summary rows.
+#' rows were added via [summary_rows()]. The output data frames contain the
+#' `group_id` and `rowname` columns, whereby `rowname` contains descriptive stub
+#' labels for the summary rows.
 #'
 #' @inheritParams extract_cells
 #'