From 5d4f0e0e753312ce14a2e29d6abeac75d9d29b45 Mon Sep 17 00:00:00 2001
From: Romain Francois <romain@tada.science>
Date: Tue, 23 Apr 2024 09:28:00 +0200
Subject: [PATCH] more documentation for %!%

---
 R/slap.R    | 34 ++++++++++++++++++++++++++--------
 man/slap.Rd | 35 +++++++++++++++++++++++++++--------
 2 files changed, 53 insertions(+), 16 deletions(-)

diff --git a/R/slap.R b/R/slap.R
index 41323b9..6a8a45b 100644
--- a/R/slap.R
+++ b/R/slap.R
@@ -1,30 +1,48 @@
 #' Slap Operator
 #'
 #' @param expr An expression or quosure to evaluate carefully
-#' @param message A message meant to be formatted by [cli::cli_bullets()]
+#' @param message A message meant to be formatted by [cli::cli_bullets()] or a
+#'   function.
+#'
+#' @return If `expr` succeeds, its result is returned.
 #'
 #' When `expr` generates an error, the `%!%` and `%!!%` operators
-#' catch it and embed it in a new error thrown by [cli::cli_abort()]
-#' with `message`.
+#' catch it and embed it in a new error thrown by [cli::cli_abort()].
+#'
+#' If `message` evaluates to a character vector, it is used as the
+#' `message` argument of [cli::cli_abort()].
+#'
+#' If `message` evaluates to a function, the function is called with one
+#' argument: the caught error from evaluating `expr`.
 #'
 #' When the current environment has an `error_call` object, it is
-#' used as the `call` argument of [cli::cli_abort()]
+#' used as the `call` argument of [cli::cli_abort()].
 #'
 #' @examples
-#'
+#' # g() throws an error
 #' g <- function() {
 #'   stop("ouch")
 #' }
+#'
+#' # h() catches that error and embed it in a new error
+#' # with "bam" as its message, the g() error as the parent error,
+#' # and the caller environment as call=
 #' h <- function(error_call = rlang::caller_env()) {
 #'   g() %!% "bam"
 #' }
+#'
+#' # f() will be used as the error call
 #' f <- function() {
 #'   h()
 #' }
 #'
-#' \dontrun{
-#'   f()
-#' }
+#' # Error in `f()`:
+#' # ! bam
+#' # Caused by error in `g()`:
+#' # ! ouch
+#' tryCatch(f(), error = function(err) {
+#'   print(err, backtrace = FALSE)
+#' })
 #'
 #' @name slap
 #' @export
diff --git a/man/slap.Rd b/man/slap.Rd
index 01a6133..0f4dcc0 100644
--- a/man/slap.Rd
+++ b/man/slap.Rd
@@ -13,32 +13,51 @@ expr \%!!\% message
 \arguments{
 \item{expr}{An expression or quosure to evaluate carefully}
 
-\item{message}{A message meant to be formatted by \code{\link[cli:cli_bullets]{cli::cli_bullets()}}
+\item{message}{A message meant to be formatted by \code{\link[cli:cli_bullets]{cli::cli_bullets()}} or a
+function.}
+}
+\value{
+If \code{expr} succeeds, its result is returned.
 
 When \code{expr} generates an error, the \verb{\%!\%} and \verb{\%!!\%} operators
-catch it and embed it in a new error thrown by \code{\link[cli:cli_abort]{cli::cli_abort()}}
-with \code{message}.
+catch it and embed it in a new error thrown by \code{\link[cli:cli_abort]{cli::cli_abort()}}.
+
+If \code{message} evaluates to a character vector, it is used as the
+\code{message} argument of \code{\link[cli:cli_abort]{cli::cli_abort()}}.
+
+If \code{message} evaluates to a function, the function is called with one
+argument: the caught error from evaluating \code{expr}.
 
 When the current environment has an \code{error_call} object, it is
-used as the \code{call} argument of \code{\link[cli:cli_abort]{cli::cli_abort()}}}
+used as the \code{call} argument of \code{\link[cli:cli_abort]{cli::cli_abort()}}.
 }
 \description{
 Slap Operator
 }
 \examples{
-
+# g() throws an error
 g <- function() {
   stop("ouch")
 }
+
+# h() catches that error and embed it in a new error
+# with "bam" as its message, the g() error as the parent error,
+# and the caller environment as call=
 h <- function(error_call = rlang::caller_env()) {
   g() \%!\% "bam"
 }
+
+# f() will be used as the error call
 f <- function() {
   h()
 }
 
-\dontrun{
-  f()
-}
+# Error in `f()`:
+# ! bam
+# Caused by error in `g()`:
+# ! ouch
+tryCatch(f(), error = function(err) {
+  print(err, backtrace = FALSE)
+})
 
 }