From b8efbd95d70b568655285b59694963a8493ce26f Mon Sep 17 00:00:00 2001
From: Henrik Bengtsson <henrik.bengtsson@gmail.com>
Date: Fri, 18 Oct 2024 23:15:41 -0700
Subject: [PATCH] Clarify that withProgressShiny() should be used for Shiny
 apps - not with_progress() [#171]

---
 DESCRIPTION          | 2 +-
 R/with_progress.R    | 6 +++++-
 man/with_progress.Rd | 6 +++++-
 3 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/DESCRIPTION b/DESCRIPTION
index 44f80ae..5896302 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -1,5 +1,5 @@
 Package: progressr
-Version: 0.14.0-9004
+Version: 0.14.0-9005
 Title: An Inclusive, Unifying API for Progress Updates
 Description: A minimal, unifying API for scripts and packages to report progress updates from anywhere including when using parallel processing.  The package is designed such that the developer can to focus on what progress should be reported on without having to worry about how to present it.  The end user has full control of how, where, and when to render these progress updates, e.g. in the terminal using utils::txtProgressBar(), cli::cli_progress_bar(), in a graphical user interface using utils::winProgressBar(), tcltk::tkProgressBar() or shiny::withProgress(), via the speakers using beepr::beep(), or on a file system via the size of a file. Anyone can add additional, customized, progression handlers. The 'progressr' package uses R's condition framework for signaling progress updated. Because of this, progress can be reported from almost anywhere in R, e.g. from classical for and while loops, from map-reduce API:s like the lapply() family of functions, 'purrr', 'plyr', and 'foreach'. It will also work with parallel processing via the 'future' framework, e.g. future.apply::future_lapply(), furrr::future_map(), and 'foreach' with 'doFuture'. The package is compatible with Shiny applications.
 Authors@R: c(person("Henrik", "Bengtsson",
diff --git a/R/with_progress.R b/R/with_progress.R
index 81e5096..168fc77 100644
--- a/R/with_progress.R
+++ b/R/with_progress.R
@@ -38,6 +38,9 @@
 #' @example incl/with_progress.R
 #'
 #' @details
+#' If you are writing a Shiny app, use the [withProgressShiny()] function
+#' instead of this one.
+#'
 #' If the global progression handler is enabled, it is temporarily disabled
 #' while evaluating the `expr` expression.
 #'
@@ -69,7 +72,8 @@
 #' will.
 #'
 #' @seealso
-#' [base::withCallingHandlers()]
+#' For Shiny apps, use [withProgressShiny()] instead of this function.
+#' Internally, this function is built around [base::withCallingHandlers()].
 #'
 #' @export
 with_progress <- function(expr, handlers = progressr::handlers(), cleanup = TRUE, delay_terminal = NULL, delay_stdout = NULL, delay_conditions = NULL, interrupts = getOption("progressr.interrupts", TRUE), interval = NULL, enable = NULL) {
diff --git a/man/with_progress.Rd b/man/with_progress.Rd
index 4ce826f..50eceeb 100644
--- a/man/with_progress.Rd
+++ b/man/with_progress.Rd
@@ -60,6 +60,9 @@ Returns the value of the expression.
 Report on Progress while Evaluating an R Expression
 }
 \details{
+If you are writing a Shiny app, use the \code{\link[=withProgressShiny]{withProgressShiny()}} function
+instead of this one.
+
 If the global progression handler is enabled, it is temporarily disabled
 while evaluating the \code{expr} expression.
 
@@ -152,5 +155,6 @@ with_progress({
 })
 }
 \seealso{
-\code{\link[base:conditions]{base::withCallingHandlers()}}
+For Shiny apps, use \code{\link[=withProgressShiny]{withProgressShiny()}} instead of this function.
+Internally, this function is built around \code{\link[base:conditions]{base::withCallingHandlers()}}.
 }