Add examples to documentation: Part-7 (q-s)

R/function_left_parentheses_linter.R

@@ -30,19 +30,15 @@
 #' )
 #'
 #' lint(
-#'   text =  "if (TRUE) x else y",
-#'   linters = function_left_parentheses_linter()
-#' )
-#'
-#' lint(
 #'   text =  "foo <- function(x) (x + 1)",
 #'   linters = function_left_parentheses_linter()
 #' )
 #'
 #' @evalRd rd_tags("function_left_parentheses_linter")
 #' @seealso
 #'   [linters] for a complete list of linters available in lintr. \cr
-#'   <https://style.tidyverse.org/syntax.html#parentheses>
+#'   <https://style.tidyverse.org/syntax.html#parentheses> \cr
+#'   [spaces_left_parentheses_linter()]
 #' @export
 function_left_parentheses_linter <- function() { # nolint: object_length.
   xpath <- "

R/redundant_equals_linter.R

@@ -6,6 +6,33 @@
 #'   can be done using prefixes (is, has, can, etc.). For example, `is_child`,
 #'   `has_parent_supervision`, `can_watch_horror_movie` clarify their logical
 #'   nature, while `child`, `parent_supervision`, `watch_horror_movie` don't.
+#'
+#' @examples
+#' # will produce lints
+#' lint(
+#'   text = "if (any(x == TRUE)) 1",
+#'   linters = redundant_equals_linter()
+#' )
+#'
+#' lint(
+#'   text = "if (any(x != FALSE)) 0",
+#'   linters = redundant_equals_linter()
+#' )
+#'
+#' # okay
+#' lint(
+#'   text = "if (any(x)) 1",
+#'   linters = redundant_equals_linter()
+#' )
+#'
+#' lint(
+#'   text = "if (!all(x)) 0",
+#'   linters = redundant_equals_linter()
+#' )
+#'
+#' @evalRd rd_tags("redundant_equals_linter")
+#' @seealso [linters] for a complete list of linters available in lintr. \cr
+#'   [outer_negation_linter()]
 #' @export
 redundant_equals_linter <- function() {
   xpath <- paste0(

R/redundant_ifelse_linter.R

@@ -9,6 +9,38 @@
 #' @param allow10 Logical, default `FALSE`. If `TRUE`, usage like
 #'   `ifelse(x, 1, 0)` is allowed, i.e., only usage like
 #'   `ifelse(x, TRUE, FALSE)` is linted.
+#'
+#' @examples
+#' # will produce lints
+#' lint(
+#'   text = "ifelse(x >= 2.5, TRUE, FALSE)",
+#'   linters = redundant_ifelse_linter()
+#' )
+#'
+#' lint(
+#'   text = "ifelse(x < 2.5, 1L, 0L)",
+#'   linters = redundant_ifelse_linter()
+#' )
+#'
+#' # okay
+#' lint(
+#'   text = "x >= 2.5",
+#'   linters = redundant_ifelse_linter()
+#' )
+#'
+#' # Note that this is just to show the strict equivalent of the example above;
+#' # converting to integer is often unnecessary and the logical vector itself
+#' # should suffice.
+#' lint(
+#'   text = "as.integer(x < 2.5)",
+#'   linters = redundant_ifelse_linter()
+#' )
+#'
+#' lint(
+#'   text = "ifelse(x < 2.5, 1L, 0L)",
+#'   linters = redundant_ifelse_linter(allow10 = TRUE)
+#' )
+#'
 #' @seealso [linters] for a complete list of linters available in lintr.
 #' @export
 redundant_ifelse_linter <- function(allow10 = FALSE) {

R/regex_subset_linter.R

@@ -20,6 +20,30 @@
 #'   to match the pattern on `levels(x)` and use that to subset instead.
 #'
 #' @evalRd rd_tags("regex_subset_linter")
+#'
+#' @examples
+#' # will produce lints
+#' lint(
+#'   text = "x[grep(pattern, x)]",
+#'   linters = regex_subset_linter()
+#' )
+#'
+#' lint(
+#'   text = "x[stringr::str_which(x, pattern)]",
+#'   linters = regex_subset_linter()
+#' )
+#'
+#' # okay
+#' lint(
+#'   text = "grep(pattern, x, value = TRUE)",
+#'   linters = regex_subset_linter()
+#' )
+#'
+#' lint(
+#'   text = "stringr::str_subset(x, pattern)",
+#'   linters = regex_subset_linter()
+#' )
+#'
 #' @seealso [linters] for a complete list of linters available in lintr.
 #' @export
 regex_subset_linter <- function() {

R/semicolon_linter.R

@@ -6,6 +6,54 @@
 #'   semicolons (e.g. as in `x; y`, i.e., on the same line of code) are allowed.
 #' @param allow_trailing Logical, default `FALSE`. If `TRUE`, "trailing"
 #'   semicolons (i.e., those that terminate lines of code) are allowed.
+#'
+#' @examples
+#' # will produce lints
+#' lint(
+#'   text = "a <- 1;",
+#'   linters = semicolon_linter()
+#' )
+#'
+#' lint(
+#'   text = "a <- 1; b <- 1",
+#'   linters = semicolon_linter()
+#' )
+#'
+#' lint(
+#'   text = "function() { a <- 1; b <- 1 }",
+#'   linters = semicolon_linter()
+#' )
+#'
+#' # okay
+#' lint(
+#'   text = "a <- 1",
+#'   linters = semicolon_linter()
+#' )
+#'
+#' lint(
+#'   text = "a <- 1;",
+#'   linters = semicolon_linter(allow_trailing = TRUE)
+#' )
+#'
+#' code_lines <- "a <- 1\nb <- 1"
+#' writeLines(code_lines)
+#' lint(
+#'   text = code_lines,
+#'   linters = semicolon_linter()
+#' )
+#'
+#' lint(
+#'   text = "a <- 1; b <- 1",
+#'   linters = semicolon_linter(allow_compound = TRUE)
+#' )
+#'
+#' code_lines <- "function() { \n  a <- 1\n  b <- 1\n}"
+#' writeLines(code_lines)
+#' lint(
+#'   text = code_lines,
+#'   linters = semicolon_linter()
+#' )
+#'
 #' @evalRd rd_tags("semicolon_linter")
 #' @seealso
 #'   [linters] for a complete list of linters available in lintr. \cr

R/seq_linter.R

@@ -9,6 +9,39 @@
 #' These often cause bugs when the right-hand side is zero.
 #' It is safer to use [base::seq_len()] or [base::seq_along()] instead.
 #'
+#' @examples
+#' # will produce lints
+#' lint(
+#'   text = "seq(length(x))",
+#'   linters = seq_linter()
+#' )
+#'
+#' lint(
+#'   text = "1:nrow(x)",
+#'   linters = seq_linter()
+#' )
+#'
+#' lint(
+#'   text = "dplyr::mutate(x, .id = 1:n())",
+#'   linters = seq_linter()
+#' )
+#'
+#' # okay
+#' lint(
+#'   text = "seq_along(x)",
+#'   linters = seq_linter()
+#' )
+#'
+#' lint(
+#'   text = "seq_len(nrow(x))",
+#'   linters = seq_linter()
+#' )
+#'
+#' lint(
+#'   text = "dplyr::mutate(x, .id = seq_len(n()))",
+#'   linters = seq_linter()
+#' )
+#'
 #' @evalRd rd_tags("seq_linter")
 #' @seealso [linters] for a complete list of linters available in lintr.
 #' @export

R/single_quotes_linter.R

@@ -2,13 +2,41 @@
 #'
 #' Check that only double quotes are used to delimit string constants.
 #'
+#' @examples
+#' # will produce lints
+#' lint(
+#'   text = "c('a', 'b')",
+#'   linters = single_quotes_linter()
+#' )
+#'
+#' # okay
+#' lint(
+#'   text = 'c("a", "b")',
+#'   linters = single_quotes_linter()
+#' )
+#'
+#' code_lines <- "paste0(x, '\"this is fine\"')"
+#' writeLines(code_lines)
+#' lint(
+#'   text = code_lines,
+#'   linters = single_quotes_linter()
+#' )
+#'
 #' @evalRd rd_tags("single_quotes_linter")
 #' @seealso
 #'   [linters] for a complete list of linters available in lintr. \cr
 #'   <https://style.tidyverse.org/syntax.html#character-vectors>
 #' @export
 single_quotes_linter <- function() {
-  squote_regex <- rex(start, zero_or_one(character_class("rR")), single_quote, any_non_double_quotes, single_quote, end)
+  squote_regex <- rex(
+    start,
+    zero_or_one(character_class("rR")),
+    single_quote,
+    any_non_double_quotes,
+    single_quote,
+    end
+  )
+
   Linter(function(source_expression) {
     if (!is_lint_level(source_expression, "file")) {
       return(list())

R/spaces_inside_linter.R

@@ -4,6 +4,29 @@
 #'   inside them, i.e., directly following an opening delimiter or directly
 #'   preceding a closing delimiter.
 #'
+#' @examples
+#' # will produce lints
+#' lint(
+#'   text = "c( TRUE, FALSE )",
+#'   linters = spaces_inside_linter()
+#' )
+#'
+#' lint(
+#'   text = "x[ 1L ]",
+#'   linters = spaces_inside_linter()
+#' )
+#'
+#' # okay
+#' lint(
+#'   text = "c(TRUE, FALSE)",
+#'   linters = spaces_inside_linter()
+#' )
+#'
+#' lint(
+#'   text = "x[1L]",
+#'   linters = spaces_inside_linter()
+#' )
+#'
 #' @evalRd rd_tags("spaces_inside_linter")
 #' @seealso
 #'   [linters] for a complete list of linters available in lintr. \cr

R/spaces_left_parentheses_linter.R

@@ -2,10 +2,24 @@
 #'
 #' Check that all left parentheses have a space before them unless they are in a function call.
 #'
+#' @examples
+#' # will produce lints
+#' lint(
+#'   text = "if(TRUE) x else y",
+#'   linters = spaces_left_parentheses_linter()
+#' )
+#'
+#' # okay
+#' lint(
+#'   text = "if (TRUE) x else y",
+#'   linters = spaces_left_parentheses_linter()
+#' )
+#'
 #' @evalRd rd_tags("spaces_left_parentheses_linter")
 #' @seealso
 #'   [linters] for a complete list of linters available in lintr. \cr
-#'   <https://style.tidyverse.org/syntax.html#parentheses>
+#'   <https://style.tidyverse.org/syntax.html#parentheses> \cr
+#'   [function_left_parentheses_linter()]
 #' @export
 spaces_left_parentheses_linter <- function() {
   file_level_xpath <- "//OP-LEFT-PAREN[@start - 1 = ancestor::expr/preceding-sibling::OP-SEMICOLON/@end]"

R/sprintf_linter.R

@@ -1,7 +1,25 @@
 #' Require correct `sprintf()` calls
 #'
-#' Check for an inconsistent number of arguments or arguments with incompatible types (for literal arguments) in
-#' `sprintf()` calls.
+#' Check for an inconsistent number of arguments or arguments with incompatible types
+#' (for literal arguments) in `sprintf()` calls.
+#'
+#' @examples
+#' # will produce lints
+#' lint(
+#'   text = "sprintf('hello %s %s %d', x, y)",
+#'   linters = sprintf_linter()
+#' )
+#'
+#' # okay
+#' lint(
+#'   text = "sprintf('hello %s %s %d', x, y, z)",
+#'   linters = sprintf_linter()
+#' )
+#'
+#' lint(
+#'   text = "sprintf('hello %s %s %d', x, y, ...)",
+#'   linters = sprintf_linter()
+#' )
 #'
 #' @evalRd rd_tags("sprintf_linter")
 #' @seealso [linters] for a complete list of linters available in lintr.

R/string_boundary_linter.R

@@ -21,6 +21,37 @@
 #'   are ignored. Some authors may prefer the conciseness offered by `grepl()` whereby
 #'   `NA` input maps to `FALSE` output, which doesn't have a direct equivalent
 #'   with `startsWith()` or `endsWith()`.
+#'
+#' @examples
+#' # will produce lints
+#' lint(
+#'   text = 'grepl("^a", x)',
+#'   linters = string_boundary_linter()
+#' )
+#'
+#' lint(
+#'   text = 'grepl("z$", x)',
+#'   linters = string_boundary_linter()
+#' )
+#'
+#' # okay
+#' lint(
+#'   text = 'startsWith(x, "a")',
+#'   linters = string_boundary_linter()
+#' )
+#'
+#' lint(
+#'   text = 'endsWith(x, "z")',
+#'   linters = string_boundary_linter()
+#' )
+#'
+#' # If missing values are present, the suggested alternative wouldn't be strictly
+#' # equivalent, so this linter can also be turned off in such cases.
+#' lint(
+#'   text = 'grepl("z$", x)',
+#'   linters = string_boundary_linter(allow_grepl = TRUE)
+#' )
+#'
 #' @evalRd rd_tags("string_boundary_linter")
 #' @seealso [linters] for a complete list of linters available in lintr.
 #' @export