Doc improvements (#291)

* Document return argument of glue()

Fixes #283

* Pass along all glue() arguments in glue_sql()

Fixes #274

* Clarify the `...` overides `.x`

Fixes #264.

* Document more return values + general tweaks

---------

Co-authored-by: Jenny Bryan <jenny.f.bryan@gmail.com>

R/color.R

@@ -22,6 +22,7 @@
 #' character, specify `.literal = TRUE`.
 #'
 #' @inheritParams glue
+#' @inherit glue return
 #' @export
 #' @examplesIf require(crayon)
 #' library(crayon)

R/glue.R

@@ -8,6 +8,8 @@
 #' @param ... \[`expressions`]\cr Unnamed arguments are taken to be expression
 #'     string(s) to format. Multiple inputs are concatenated together before formatting.
 #'     Named arguments are taken to be temporary variables available for substitution.
+#'
+#'     For `glue_data()`, elements in `...` override the values in `.x`.
 #' @param .sep \[`character(1)`: \sQuote{""}]\cr Separator used to separate elements.
 #' @param .envir \[`environment`: `parent.frame()`]\cr Environment to evaluate each expression in. Expressions are
 #'   evaluated from left to right. If `.x` is an environment, the expressions are
@@ -38,6 +40,7 @@
 #'   template with [trim()] or not.
 #' @seealso <https://www.python.org/dev/peps/pep-0498/> and
 #'   <https://www.python.org/dev/peps/pep-0257/> upon which this is based.
+#' @returns A glue object, as created by [as_glue()].
 #' @examples
 #' name <- "Fred"
 #' age <- 50
@@ -216,14 +219,14 @@ glue <- function(..., .sep = "", .envir = parent.frame(), .open = "{", .close =
 #' @param last String used to separate the last two items if `x` has at least
 #' 2 items.
 #' @inheritParams base::paste
+#' @inherit glue return
 #' @examples
 #' glue_collapse(glue("{1:10}"))
 #'
 #' # Wide values can be truncated
 #' glue_collapse(glue("{1:10}"), width = 5)
 #'
 #' glue_collapse(1:4, ", ", last = " and ")
-#' #> 1, 2, 3 and 4
 #' @export
 glue_collapse <- function(x, sep = "", width = Inf, last = "") {
   if (length(x) == 0) {
@@ -258,6 +261,7 @@ glue_collapse <- function(x, sep = "", width = Inf, last = "") {
 #' to the minimum indentation of all non-blank lines after the first.
 #' - Lines can be continued across newlines by using `\\`.
 #' @param x A character vector to trim.
+#' @returns A character vector.
 #' @export
 #' @examples
 #' glue("
@@ -297,9 +301,23 @@ print.glue <- function(x, ..., sep = "\n") {
 }
 
 #' Coerce object to glue
+#'
+#' A glue object is a character vector with S3 class `"glue"`. The `"glue"`
+#' class implements a print method that shows the literal contents (rather than
+#' the string implementation) and a `+` method, so that you can concatenate with
+#' the addition operator.
+#'
 #' @param x object to be coerced.
 #' @param ... further arguments passed to methods.
+#' @returns A character vector with S3 class `"glue"`.
 #' @export
+#' @examples
+#' x <- as_glue(c("abc", "\"\\\\", "\n"))
+#' x
+#'
+#' x <- 1
+#' y <- 3
+#' glue("x + y") + " = {x + y}"
 as_glue <- function(x, ...) {
   UseMethod("as_glue")
 }

R/quoting.R

@@ -1,9 +1,11 @@
 #' Quoting operators
 #'
 #' These functions make it easy to quote each individual element and are useful
-#' in conjunction with [glue_collapse()].
+#' in conjunction with [glue_collapse()]. These are thin wrappers around
+#' [base::encodeString()].
 #' @param x A character to quote.
 #' @name quoting
+#' @inherit base::encodeString return
 #' @export
 #' @examples
 #' x <- 1:5

R/safe.R

@@ -6,6 +6,7 @@
 #' with untrusted input, such as inputs in a Shiny application, where using the
 #' normal functions would allow an attacker to execute arbitrary code.
 #' @inheritParams glue
+#' @inherit glue return
 #' @export
 #' @examples
 #' "1 + 1" <- 5

R/sql.R

@@ -1,5 +1,6 @@
 #' Interpolate strings with SQL escaping
 #'
+#' @description
 #' SQL databases often have custom quotation syntax for identifiers and strings
 #' which make writing SQL queries error prone and cumbersome to do. `glue_sql()` and
 #' `glue_data_sql()` are analogs to [glue()] and [glue_data()] which handle the
@@ -134,14 +135,61 @@
 #'
 #' DBI::dbDisconnect(con)
 #' @export
-glue_sql <- function(..., .con, .envir = parent.frame(), .na = DBI::SQL("NULL")) {
-  DBI::SQL(glue(..., .envir = .envir, .na = .na, .transformer = sql_quote_transformer(.con, .na)))
+glue_sql <- function(...,
+                     .con,
+                     .sep = "",
+                     .envir = parent.frame(),
+                     .open = "{",
+                     .close = "}",
+                     .na = DBI::SQL("NULL"),
+                     .null = character(),
+                     .comment = "#",
+                     .literal = FALSE,
+                     .trim = TRUE
+                     ) {
+  DBI::SQL(glue(
+    ...,
+    .sep = .sep,
+    .envir = .envir,
+    .open = .open,
+    .close = .close,
+    .na = .na,
+    .null = .null,
+    .comment = .comment,
+    .literal = .literal,
+    .transformer = sql_quote_transformer(.con, .na),
+    .trim = .trim
+  ))
 }
 
 #' @rdname glue_sql
 #' @export
-glue_data_sql <- function(.x, ..., .con, .envir = parent.frame(), .na = DBI::SQL("NULL")) {
-  DBI::SQL(glue_data(.x, ..., .envir = .envir, .na = .na, .transformer = sql_quote_transformer(.con, .na)))
+glue_data_sql <- function(.x,
+                          ...,
+                          .con,
+                          .sep = "",
+                          .envir = parent.frame(),
+                          .open = "{",
+                          .close = "}",
+                          .na = DBI::SQL("NULL"),
+                          .null = character(),
+                          .comment = "#",
+                          .literal = FALSE,
+                          .trim = TRUE) {
+  DBI::SQL(glue_data(
+    .x,
+    ...,
+    .sep = .sep,
+    .envir = .envir,
+    .open = .open,
+    .close = .close,
+    .na = .na,
+    .null = .null,
+    .comment = .comment,
+    .literal = .literal,
+    .transformer = sql_quote_transformer(.con, .na),
+    .trim = .trim
+  ))
 }
 
 #' @rdname glue_collapse