docs: improvement on join() documentation

Author: averissimo

R/qenv-c.R

@@ -50,11 +50,19 @@
   }
 }
 
-#' @export
-c.qenv.error <- function(...) {
-  rlang::list2(...)[[1]]
-}
-
+#' @rdname join
+#' @param ... (`qenv` or `qenv.error`).
+#' @examples
+#' q <- qenv()
+#' q1 <- within(q, {
+#'   iris1 <- iris
+#'   mtcars1 <- mtcars
+#' })
+#' q1 <- within(q1, iris2 <- iris)
+#' q2 <- within(q1, mtcars2 <- mtcars)
+#' qq <- c(q1, q2)
+#' cat(get_code(qq))
+#'
 #' @export
 c.qenv <- function(...) {
   dots <- rlang::list2(...)
@@ -91,3 +99,9 @@ c.qenv <- function(...) {
     }
   )
 }
+
+#' @rdname join
+#' @export
+c.qenv.error <- function(...) {
+  rlang::list2(...)[[1]]
+}

R/qenv-join.R

@@ -1,10 +1,10 @@
 #' Join `qenv` objects
 #'
 #' @description
-#' `r lifecycle::badge("superseded")` by [c()].
-#'
 #' Checks and merges two `qenv` objects into one `qenv` object.
 #'
+#' The `join()` function is superseded by the `c()` function.
+#'
 #' @details
 #' Any common code at the start of the `qenvs` is only placed once at the start of the joined `qenv`.
 #' This allows consistent behavior when joining `qenvs` which share a common ancestor.
@@ -19,7 +19,7 @@
 #'    x <- eval_code(qenv(), expression(mtcars1 <- mtcars))
 #'    y <- eval_code(qenv(), expression(mtcars1 <- mtcars['wt']))
 #'
-#'    z <- join(x, y)
+#'    z <- c(x, y)
 #'    # Error message will occur
 #'    ```
 #'    In this example, `mtcars1` object exists in both `x` and `y` objects but the content are not identical.
@@ -44,8 +44,8 @@
 #'      y,
 #'      "z <- v"
 #'    )
-#'    q <- join(x, y)
-#'    join_q <- join(q, z)
+#'    q <- c(x, y)
+#'    join_q <- c(q, z)
 #'    # Error message will occur
 #'
 #'    # Check the order of evaluation based on the id slot
@@ -78,10 +78,10 @@
 #'    # Error message will occur
 #'
 #'    # Check the value of temporary variable i in both objects
-#'    x@.xData$i # Output: 2
-#'    y@.xData$i # Output: 3
+#'    x$i # Output: 2
+#'    y$i # Output: 3
 #'    ```
-#'    `join()` fails to provide a proper result because of the temporary variable `i` exists
+#'    `c()` and `join()` fails to provide a proper result because of the temporary variable `i` exists
 #'    in both objects but has different value.
 #'    To fix this, we can set `i <- NULL` in the code expression for both objects.
 #'    ```r
@@ -104,7 +104,7 @@
 #'       # dummy i variable to fix it
 #'       i <- NULL"
 #'    )
-#'    q <- join(x,y)
+#'    q <- c(x,y)
 #'    ```
 #'
 #' @param x (`qenv`)
@@ -119,14 +119,14 @@
 #' q1 <- eval_code(q1, "iris2 <- iris")
 #' q2 <- eval_code(q2, "mtcars2 <- mtcars")
 #' qq <- join(q1, q2)
-#' get_code(qq)
+#' cat(get_code(qq))
 #'
 #' common_q <- eval_code(q, quote(x <- 1))
 #' y_q <- eval_code(common_q, quote(y <- x * 2))
 #' z_q <- eval_code(common_q, quote(z <- x * 3))
 #' join_q <- join(y_q, z_q)
 #' # get_code only has "x <- 1" occurring once
-#' get_code(join_q)
+#' cat(get_code(join_q))
 #'
 #' @include qenv-errors.R
 #'