Update documentation

R/DELIMITERS-end_expr.R

@@ -1,6 +1,6 @@
 #' End and evaluate expression
 #'
-#' Finish the expression building process and evaluate it.
+#' Finish the expression-building process and evaluate it.
 #'
 #' @export
 #'
@@ -16,9 +16,9 @@ end_expr <- function(.data, ...) {
 #' @importFrom rlang caller_env
 #' @importFrom rlang is_missing
 #'
-#' @param .by_ref Whether to use [data.table::copy()] before evaluation.
+#' @param .by_ref If `FALSE`, [data.table::copy()] is used before evaluation.
 #' @param .parent_env Optionally, the *enclosing* environment of the expression's evaluation
-#'   environment.
+#'   environment. Defaults to the caller environment.
 #'
 #' @details
 #'
@@ -34,3 +34,4 @@ end_expr.ExprBuilder <- function(.data, ..., .by_ref = TRUE, .parent_env) {
         .data$eval(.parent_env, .by_ref)
     }
 }
+

R/VERBS-filter_on.R

@@ -8,8 +8,7 @@
 #'
 #' @template data-arg
 #' @param ... Key-value pairs, see details.
-#' @param nomatch See [data.table::data.table].
-#' @param mult See [data.table::data.table].
+#' @param nomatch,mult See [data.table::data.table].
 #' @param .negate Whether to negate the expression and search only for rows that don't contain the
 #'   given values.
 #' @template chain-arg

R/VERBS-group_by.R

@@ -3,9 +3,9 @@
 #'
 dplyr::group_by
 
-#' Group by clause
+#' Grouping clauses
 #'
-#' Aggregations for a [data.table::data.table-class].
+#' Grouping by columns of a [data.table::data.table].
 #'
 #' @rdname group_by-table.express
 #' @name group_by-table.express

R/VERBS-joins.R

@@ -10,10 +10,7 @@
 #' @param x An [ExprBuilder] instance.
 #' @param y A [data.table::data.table-class].
 #' @param ... Expressions for the `on` part of the join.
-#' @param nomatch See [data.table::data.table].
-#' @param mult See [data.table::data.table].
-#' @param roll See [data.table::data.table].
-#' @param rollends See [data.table::data.table].
+#' @param nomatch,mult,roll,rollends See [data.table::data.table].
 #' @param .parent_env See [end_expr()].
 #' @param .SDcols For `mutate_join`. See the details below.
 #' @param sort Passed to [data.table::merge].

R/pkg.R

@@ -1,7 +1,8 @@
 #' Building 'data.table' expressions with data manipulation verbs
 #'
-#' A specialization of [dplyr::dplyr-package] verbs, as well as a set of custom ones, that build
-#' expressions that can be used within a [data.table::data.table-package]'s frame.
+#' A specialization of [`dplyr`][dplyr::dplyr-package] verbs, as well as a set of custom ones, that
+#' build expressions that can be used within a [`data.table`][data.table::data.table-package]'s
+#' frame.
 #'
 #' @author Alexis Sarda-Espinosa
 #'

vignettes/joins.Rmd

@@ -221,9 +221,6 @@ The last example specifies `by = .EACHI` in the joining expression.
 
 ## Rolling joins
 
-A nice blog post describing rolling joins can be found at [R-bloggers](https://www.r-bloggers.com/understanding-data-table-rolling-joins/),
-so almost the same `website` and `paypal` tables will be used for the examples below.
-
 ```{r rolling-join-data, echo=FALSE}
 website <- data.table::rbindlist(list(
     data.table::data.table(
@@ -290,7 +287,13 @@ data.table::setkey(paypal, name, purchase_time)
 
 website[, session_id := .GRP, by = .(name, session_start_time)]
 paypal[, payment_id := .GRP, by = .(name, purchase_time)]
+```
 
+A nice blog post describing rolling joins can be found at [R-bloggers](https://www.r-bloggers.com/understanding-data-table-rolling-joins/),
+so almost the same `website` and `paypal` tables will be used for the examples below.
+Another short description with animated depictions can also be found [here](https://www.gormanalysis.com/blog/r-data-table-rolling-joins/).
+
+```{r rolling-join-data-print}
 print(website)
 print(paypal)
 ```
@@ -311,7 +314,8 @@ paypal %>%
 We can see that the rows returned are from the left-hand side (`paypal`),
 and since neither Mom nor Erica visited the website before their purchases,
 their `session_id` ended as `NA`.
-Moreover, the order of the columns in the `on` expressions is the same as [above](#basic-joins).
+
+The order of the columns in the `on` expressions is the same as [above](#basic-joins).
 The tricky part is that the rolled column ended up with the name from the right-hand side,
 but keeping the values from the left-hand side.
 If we "invert" the join,

vignettes/table.express.Rmd

@@ -289,7 +289,7 @@ and columns that are not part of `.SDcols` are kept:
 ```{r mutate-sd}
 DT %>%
   start_expr %>%
-  mutate_sd(exp, .SDcols = c("mpg", "cyl")) %>%
+  mutate_sd(c("mpg", "cyl"), exp) %>%
   end_expr
 
 print(DT)
@@ -319,7 +319,7 @@ print(DT)
 # like dplyr's mutate_if
 DT %>%
   start_expr %>%
-  mutate_sd(as.integer(.COL), .SDcols = all(.COL %% 1 == 0))
+  mutate_sd(all(.COL %% 1 == 0), as.integer(.COL))
 ```
 
 On the other hand, `transmute_sd` never modifies by reference,
@@ -330,18 +330,18 @@ as well as another special pronoun: `.COLNAME`:
 ```{r transmute-sd}
 DT %>%
   start_expr %>%
-  transmute_sd(.COL * 2, .SDcols = starts_with("d")) %>%
+  transmute_sd(starts_with("d"), .COL * 2) %>%
   end_expr
 
 DT %>%
   start_expr %>%
-  transmute_sd(.COL * 2, .SDcols = grepl("^d", .COLNAME)) %>%
+  transmute_sd(grepl("^d", .COLNAME), .COL * 2) %>%
   end_expr
 
 # like dplyr's transmute_if
 DT %>%
   start_expr %>%
-  transmute_sd(.COL * 2, .SDcols = is.numeric(.COL)) %>%
+  transmute_sd(is.numeric(.COL), .COL * 2) %>%
   end_expr
 ```
 
@@ -443,9 +443,11 @@ which would lead to a warning being shown whenever a part of the query is replac
   - `mutate_sd`
   - `transmute`
   - `transmute_sd`
+  - `distinct`
 - Verbs for grouping:
   - `group_by` to specify `by`
   - `key_by` to specify `keyby`
+  - `distinct`
 
 ## Explicit chaining
 
@@ -506,7 +508,7 @@ DT %>%
   start_expr %>%
   select(mpg:disp) %>%
   transmute(ans = sqrt(mpg)) %>%
-  filter_sd(.COL > 0, .SDcols = contains("m"))
+  filter_sd(contains("m"), .COL > 0)
 ```
 
 The `select` gets rid of `am`,
@@ -520,7 +522,7 @@ DT %>%
   select(mpg:disp) %>%
   chain %>%
   transmute(ans = sqrt(mpg)) %>%
-  filter_sd(.COL > 0, .SDcols = contains("m"))
+  filter_sd(contains("m"), .COL > 0)
 ```
 
 ## As simple as possible