Add source-code comments to clarify with_progress() + add one invisible() for consistency [#178]

Author: HenrikBengtsson

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: progressr
-Version: 0.16.0-9003
+Version: 0.16.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",

R/make_calling_handler.R

@@ -6,7 +6,7 @@ make_calling_handler <- function(handlers) {
         handler <- handlers[[kk]]
         if (handler(p)) finished <- TRUE
       }
-      finished
+      invisible(finished)
     }
   } else {
     calling_handler <- handlers[[1]]

R/with_progress.R

@@ -157,7 +157,7 @@ with_progress <- function(expr, handlers = progressr::handlers(), cleanup = TRUE
     ## Flag indicating whether nor not with_progress() exited due to an error
     status <- "incomplete"
 
-    ## Tell all progression handlers to shutdown at the end and
+    ## Tell all progression handlers to shut down at the end and
     ## the status of the evaluation.
     if (cleanup) {
       on.exit({
@@ -238,8 +238,11 @@ with_progress <- function(expr, handlers = progressr::handlers(), cleanup = TRUE
           calling_handler(control_progression("unhide"))
         }
       }
-      
-      calling_handler(p)
+
+      ## Let the registered 'progressr' calling handlers process
+      ## the 'progression' condition. If the progressor completed,
+      ## then 'finished' is TRUE (which we currently don't use)
+      finished <- calling_handler(p)
     },
 
     interrupt = handle_interrupt_or_error,