From 9b91369dc32c65ec2187c74059f2c07d9ef2c65c Mon Sep 17 00:00:00 2001
From: shikokuchuo <53399081+shikokuchuo@users.noreply.github.com>
Date: Thu, 30 May 2024 11:00:37 +0100
Subject: [PATCH] deprecate strcat and update examples

---
 NEWS.md        |  1 +
 R/context.R    | 38 +++++++++++++++++++++-----------------
 R/sync.R       |  6 ++++--
 R/utils.R      |  2 ++
 man/cv.Rd      |  6 ++++--
 man/request.Rd | 38 +++++++++++++++++++++-----------------
 man/strcat.Rd  |  2 ++
 7 files changed, 55 insertions(+), 38 deletions(-)

diff --git a/NEWS.md b/NEWS.md
index 07e3e515f..4f3e715b7 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -10,6 +10,7 @@
 #### Updates
 
 * `recv_aio()` and `request()` add argument 'cv' allowing optional signalling of a condition variable. The separate functions `recv_aio_signal()` and `request_signal()` are deprecated.
+* `strcat()` is deprecated as considered non-core - it is recommended to replace usage with `sprintf()`.
 * `status_code()` now returns the status code combined with the explanation as a character string.
 * Performance enhancements for `unresolved()`, `call_aio()` and `call_aio_()`.
 
diff --git a/R/context.R b/R/context.R
index a5d1b8a77..d9cf0d2eb 100644
--- a/R/context.R
+++ b/R/context.R
@@ -208,32 +208,36 @@ reply <- function(context,
 #' @inheritSection recv_aio Signalling
 #'
 #' @examples
+#' \dontrun{
+#'
 #' # works if req and rep are running in parallel in different processes
 #'
-#' # req <- socket("req", listen = "tcp://127.0.0.1:6546")
-#' # rep <- socket("rep", dial = "tcp://127.0.0.1:6546")
+#' req <- socket("req", listen = "tcp://127.0.0.1:6546")
+#' rep <- socket("rep", dial = "tcp://127.0.0.1:6546")
 #'
-#' # reply(.context(rep), execute = function(x) x + 1, timeout = 50)
-#' # aio <- request(.context(req), data = 2022)
-#' # aio$data
+#' reply(.context(rep), execute = function(x) x + 1, timeout = 50)
+#' aio <- request(.context(req), data = 2022)
+#' aio$data
 #'
-#' # close(req)
-#' # close(rep)
+#' close(req)
+#' close(rep)
 #'
 #' # Signalling a condition variable
 #'
-#' # req <- socket("req", listen = "tcp://127.0.0.1:6546")
-#' # ctxq <- context(req)
-#' # cv <- cv()
-#' # aio <- request_signal(ctxq, data = 2022, cv = cv)
-#' # until(cv, 10L)
-#' # close(req)
+#' req <- socket("req", listen = "tcp://127.0.0.1:6546")
+#' ctxq <- context(req)
+#' cv <- cv()
+#' aio <- request_signal(ctxq, data = 2022, cv = cv)
+#' until(cv, 10L)
+#' close(req)
 #'
 #' # The following should be run in another process
-#' # rep <- socket("rep", dial = "tcp://127.0.0.1:6546")
-#' # ctxp <- context(rep)
-#' # reply(ctxp, execute = function(x) x + 1)
-#' # close(rep)
+#' rep <- socket("rep", dial = "tcp://127.0.0.1:6546")
+#' ctxp <- context(rep)
+#' reply(ctxp, execute = function(x) x + 1)
+#' close(rep)
+#'
+#' }
 #'
 #' @export
 #'
diff --git a/R/sync.R b/R/sync.R
index 60a771855..571b8da50 100644
--- a/R/sync.R
+++ b/R/sync.R
@@ -85,8 +85,10 @@ cv <- function() .Call(rnng_cv_alloc)
 #' @param cv a \sQuote{conditionVariable} object.
 #'
 #' @examples
-#' # wait(cv) # uncommenting will block until the cv is signalled
-#' # wait_(cv) # block until the cv is signalled or interrupted
+#' \dontrun{
+#' wait(cv) # would block until the cv is signalled
+#' wait_(cv) # would block until the cv is signalled or interrupted
+#' }
 #'
 #' @rdname cv
 #' @export
diff --git a/R/utils.R b/R/utils.R
index b239abc2a..b94c265bd 100644
--- a/R/utils.R
+++ b/R/utils.R
@@ -265,6 +265,7 @@ status_code <- function(x) .Call(rnng_status_code, x)
 #' Concatenate Strings
 #'
 #' A fast implementation that combines two character values into a single string.
+#'     This function is deprecated and will be removed in a future version.
 #'
 #' @param a character value.
 #' @param b character value.
@@ -277,6 +278,7 @@ status_code <- function(x) .Call(rnng_status_code, x)
 #' @examples
 #' strcat("hello ", "world!")
 #'
+#' @keywords internal
 #' @export
 #'
 strcat <- function(a, b) .Call(rnng_strcat, a, b)
diff --git a/man/cv.Rd b/man/cv.Rd
index ff1712553..1ac4b7d25 100644
--- a/man/cv.Rd
+++ b/man/cv.Rd
@@ -108,8 +108,10 @@ Pass the \sQuote{conditionVariable} to the signalling forms of the
 \examples{
 cv <- cv()
 
-# wait(cv) # uncommenting will block until the cv is signalled
-# wait_(cv) # block until the cv is signalled or interrupted
+\dontrun{
+wait(cv) # would block until the cv is signalled
+wait_(cv) # would block until the cv is signalled or interrupted
+}
 
 until(cv, 10L)
 until_(cv, 10L)
diff --git a/man/request.Rd b/man/request.Rd
index 935768968..aeab77f62 100644
--- a/man/request.Rd
+++ b/man/request.Rd
@@ -97,31 +97,35 @@ Sending the request and receiving the result are both performed
 }
 
 \examples{
+\dontrun{
+
 # works if req and rep are running in parallel in different processes
 
-# req <- socket("req", listen = "tcp://127.0.0.1:6546")
-# rep <- socket("rep", dial = "tcp://127.0.0.1:6546")
+req <- socket("req", listen = "tcp://127.0.0.1:6546")
+rep <- socket("rep", dial = "tcp://127.0.0.1:6546")
 
-# reply(.context(rep), execute = function(x) x + 1, timeout = 50)
-# aio <- request(.context(req), data = 2022)
-# aio$data
+reply(.context(rep), execute = function(x) x + 1, timeout = 50)
+aio <- request(.context(req), data = 2022)
+aio$data
 
-# close(req)
-# close(rep)
+close(req)
+close(rep)
 
 # Signalling a condition variable
 
-# req <- socket("req", listen = "tcp://127.0.0.1:6546")
-# ctxq <- context(req)
-# cv <- cv()
-# aio <- request_signal(ctxq, data = 2022, cv = cv)
-# until(cv, 10L)
-# close(req)
+req <- socket("req", listen = "tcp://127.0.0.1:6546")
+ctxq <- context(req)
+cv <- cv()
+aio <- request_signal(ctxq, data = 2022, cv = cv)
+until(cv, 10L)
+close(req)
 
 # The following should be run in another process
-# rep <- socket("rep", dial = "tcp://127.0.0.1:6546")
-# ctxp <- context(rep)
-# reply(ctxp, execute = function(x) x + 1)
-# close(rep)
+rep <- socket("rep", dial = "tcp://127.0.0.1:6546")
+ctxp <- context(rep)
+reply(ctxp, execute = function(x) x + 1)
+close(rep)
+
+}
 
 }
diff --git a/man/strcat.Rd b/man/strcat.Rd
index b588a952a..5100a7caf 100644
--- a/man/strcat.Rd
+++ b/man/strcat.Rd
@@ -16,6 +16,7 @@ A character string.
 }
 \description{
 A fast implementation that combines two character values into a single string.
+    This function is deprecated and will be removed in a future version.
 }
 \details{
 If either \sQuote{a} or \sQuote{b} is a vector of length greater
@@ -25,3 +26,4 @@ If either \sQuote{a} or \sQuote{b} is a vector of length greater
 strcat("hello ", "world!")
 
 }
+\keyword{internal}