From cf61f7e45c06cd946627791b7c92470f7301ded7 Mon Sep 17 00:00:00 2001 From: Hadley Wickham Date: Fri, 23 Aug 2024 13:06:51 -0500 Subject: [PATCH] Remove internal functions from the index I'm reasonably confident that we have a shared belief that these functions shouldn't be used in new code. Since we don't want to take a dependency on lifecycle, I think it's simplest to just make these functions internal and not think about them again :) --- R/color.R | 1 + R/logger.R | 1 + R/try.R | 5 +++++ R/utils.R | 13 +++++++++---- _pkgdown.yml | 10 +--------- man/colorize_by_log_level.Rd | 1 + man/deparse_to_one_line.Rd | 7 +++---- man/fail_on_missing_package.Rd | 4 +++- man/grapes-except-grapes.Rd | 5 +++-- man/logger.Rd | 1 + 10 files changed, 28 insertions(+), 20 deletions(-) diff --git a/R/color.R b/R/color.R index 7d53d065..35b65730 100644 --- a/R/color.R +++ b/R/color.R @@ -7,6 +7,7 @@ #' @param msg String to color. #' @param level see [log_levels()] #' @return A string with ANSI escape codes. +#' @keywords internal #' @export #' @examplesIf requireNamespace("crayon") #' cat(colorize_by_log_level("foobar", FATAL), "\n") diff --git a/R/logger.R b/R/logger.R index b28fa624..40db29a1 100644 --- a/R/logger.R +++ b/R/logger.R @@ -30,6 +30,7 @@ #' function), and a list of `handlers` with the `formatter`, #' `layout` and `appender` functions. #' @export +#' @keywords internal #' @references For more details, see the Anatomy of a Log Request #' vignette at #' . diff --git a/R/try.R b/R/try.R index 79eaaea0..04ffcc27 100644 --- a/R/try.R +++ b/R/try.R @@ -1,7 +1,12 @@ #' Try to evaluate an expressions and evaluate another expression on #' exception +#' +#' We do not recommend using this function in new code; it only exported +#' for historical reasons. +#' #' @param try R expression #' @param except fallback R expression to be evaluated if `try` fails +#' @keywords internal #' @export #' @note Suppress log messages in the `except` namespace if you don't #' want to throw a `WARN` log message on the exception branch. diff --git a/R/utils.R b/R/utils.R index 23faa0fc..55457feb 100644 --- a/R/utils.R +++ b/R/utils.R @@ -1,8 +1,13 @@ #' Check if R package can be loaded and fails loudly otherwise +#' +#' We do not recommend using this function in new code; it only exported +#' for historical reasons. +#' #' @param pkg string #' @param min_version optional minimum version needed #' @export #' @importFrom utils packageVersion compareVersion +#' @keywords internal #' @examples \dontrun{ #' f <- function() fail_on_missing_package("foobar") #' f() @@ -48,12 +53,12 @@ top_env_name <- function(.topenv = parent.frame()) { #' Deparse and join all lines into a single line #' -#' Calling `deparse` and joining all the returned lines into a -#' single line, separated by whitespace, and then cleaning up all the -#' duplicated whitespace (except for excessive whitespace in strings -#' between single or double quotes). +#' We do not recommend using this function in new code; it only exported +#' for historical reasons. +#' #' @param x object to `deparse` #' @return string +#' @keywords internal #' @export deparse_to_one_line <- function(x) { gsub('\\s+(?=(?:[^\\\'"]*[\\\'"][^\\\'"]*[\\\'"])*[^\\\'"]*$)', " ", diff --git a/_pkgdown.yml b/_pkgdown.yml index 05e5044e..328f2001 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -58,18 +58,10 @@ reference: - log_warnings - log_errors -- title: Other helpers - contents: - - colorize_by_log_level - - logger - - delete_logger_index - - "%except%" - - title: Dev tools contents: - as.loglevel - - deparse_to_one_line - - fail_on_missing_package - get_logger_meta_variables - log_namespaces - log_indices + - delete_logger_index diff --git a/man/colorize_by_log_level.Rd b/man/colorize_by_log_level.Rd index 54322ac0..5adccece 100644 --- a/man/colorize_by_log_level.Rd +++ b/man/colorize_by_log_level.Rd @@ -41,3 +41,4 @@ cat(grayscale_by_log_level("foobar", DEBUG), "\n") cat(grayscale_by_log_level("foobar", TRACE), "\n") \dontshow{\}) # examplesIf} } +\keyword{internal} diff --git a/man/deparse_to_one_line.Rd b/man/deparse_to_one_line.Rd index 6016a03e..a177dee8 100644 --- a/man/deparse_to_one_line.Rd +++ b/man/deparse_to_one_line.Rd @@ -13,8 +13,7 @@ deparse_to_one_line(x) string } \description{ -Calling \code{deparse} and joining all the returned lines into a -single line, separated by whitespace, and then cleaning up all the -duplicated whitespace (except for excessive whitespace in strings -between single or double quotes). +We do not recommend using this function in new code; it only exported +for historical reasons. } +\keyword{internal} diff --git a/man/fail_on_missing_package.Rd b/man/fail_on_missing_package.Rd index c0299eb7..93f5deab 100644 --- a/man/fail_on_missing_package.Rd +++ b/man/fail_on_missing_package.Rd @@ -12,7 +12,8 @@ fail_on_missing_package(pkg, min_version) \item{min_version}{optional minimum version needed} } \description{ -Check if R package can be loaded and fails loudly otherwise +We do not recommend using this function in new code; it only exported +for historical reasons. } \examples{ \dontrun{ @@ -22,3 +23,4 @@ g <- function() fail_on_missing_package("stats") g() } } +\keyword{internal} diff --git a/man/grapes-except-grapes.Rd b/man/grapes-except-grapes.Rd index 75d6fcb9..33937dd6 100644 --- a/man/grapes-except-grapes.Rd +++ b/man/grapes-except-grapes.Rd @@ -13,8 +13,8 @@ try \%except\% except \item{except}{fallback R expression to be evaluated if \code{try} fails} } \description{ -Try to evaluate an expressions and evaluate another expression on -exception +We do not recommend using this function in new code; it only exported +for historical reasons. } \note{ Suppress log messages in the \code{except} namespace if you don't @@ -30,3 +30,4 @@ FunDoesNotExist(1:10) \%except\% (sum(1:10) / length(1:10)) FunDoesNotExist(1:10) \%except\% MEAN(1:10) \%except\% mean(1:10) FunDoesNotExist(1:10) \%except\% (MEAN(1:10) \%except\% mean(1:10)) } +\keyword{internal} diff --git a/man/logger.Rd b/man/logger.Rd index 1f87ce1b..0297c7f0 100644 --- a/man/logger.Rd +++ b/man/logger.Rd @@ -65,3 +65,4 @@ For more details, see the Anatomy of a Log Request vignette at \url{https://daroczig.github.io/logger/articles/anatomy.html}. } +\keyword{internal}