Add examples to documentation: Part-6 (o-p) (#1664)

* Examples for `object_name_linter()` and `object_length_linter()`

* Examples for `outer_negation_linter()` and `object_usage_linter()`

* Examples for `package_hooks_linter()`

* Examples for `paste_linter()`

* Examples for `paren_body_linter()`

* Examples for `pipe_call_linter()` and `pipe_continuation_linter()`

* Address review comments

* rest of the cleanup

* follow style guide

R/assignment_linter.R

@@ -41,7 +41,7 @@
 #'   linters = assignment_linter(allow_cascading_assign = FALSE)
 #' )
 #'
-#' cat("foo(bar = \n 1)")
+#' writeLines("foo(bar = \n 1)")
 #' lint(
 #'   text = "foo(bar = \n 1)",
 #'   linters = assignment_linter(allow_trailing = FALSE)

R/brace_linter.R

@@ -19,27 +19,27 @@
 #'   linters = brace_linter()
 #' )
 #'
-#' cat("if (TRUE) {\n return(1) }")
+#' writeLines("if (TRUE) {\n return(1) }")
 #' lint(
 #'   text = "if (TRUE) {\n return(1) }",
 #'   linters = brace_linter()
 #' )
 #'
 #' # okay
-#' cat("f <- function() {\n  1\n}")
+#' writeLines("f <- function() {\n  1\n}")
 #' lint(
 #'   text = "f <- function() {\n  1\n}",
 #'   linters = brace_linter()
 #' )
 #'
-#' cat("if (TRUE) { \n return(1) \n}")
+#' writeLines("if (TRUE) { \n return(1) \n}")
 #' lint(
 #'   text = "if (TRUE) { \n return(1) \n}",
 #'   linters = brace_linter()
 #' )
 #'
 #' # customizing using arguments
-#' cat("if (TRUE) { return(1) }")
+#' writeLines("if (TRUE) { return(1) }")
 #' lint(
 #'   text = "if (TRUE) { return(1) }",
 #'   linters = brace_linter(allow_single_line = TRUE)

R/empty_assignment_linter.R

@@ -10,7 +10,7 @@
 #'   linters = empty_assignment_linter()
 #' )
 #'
-#' cat("x = {\n}")
+#' writeLines("x = {\n}")
 #' lint(
 #'   text = "x = {\n}",
 #'   linters = empty_assignment_linter()

R/function_return_linter.R

@@ -16,7 +16,7 @@
 #'   linters = function_return_linter()
 #' )
 #'
-#' cat("e <- new.env() \nfoo <- function(x) return(e$val <- x + 1)")
+#' writeLines("e <- new.env() \nfoo <- function(x) return(e$val <- x + 1)")
 #' lint(
 #'   text = "e <- new.env() \nfoo <- function(x) return(e$val <- x + 1)",
 #'   linters = function_return_linter()
@@ -46,7 +46,7 @@
 #'   return(e$val)
 #' }
 #' "
-#' cat(code_lines)
+#' writeLines(code_lines)
 #' lint(
 #'   text = code_lines,
 #'   linters = function_return_linter()

R/infix_spaces_linter.R

@@ -111,7 +111,7 @@ infix_overload <- data.frame(
 #' ab     <- 1L
 #' abcdef <- 2L
 #' "
-#' cat(code_lines)
+#' writeLines(code_lines)
 #' lint(
 #'   text = code_lines,
 #'   linters = infix_spaces_linter(allow_multiple_spaces = TRUE)

R/object_name_linters.R

@@ -44,6 +44,40 @@ object_name_xpath <- local({
 #' @param styles A subset of
 #'   \Sexpr[stage=render, results=rd]{lintr:::regexes_rd}. A name should
 #'   match at least one of these styles.
+#'
+#' @examples
+#' # will produce lints
+#' lint(
+#'   text = "my_var <- 1L",
+#'   linters = object_name_linter(styles = "CamelCase")
+#' )
+#'
+#' lint(
+#'   text = "xYz <- 1L",
+#'   linters = object_name_linter(styles = c("UPPERCASE", "lowercase"))
+#' )
+#'
+#' lint(
+#'   text = "MyVar <- 1L",
+#'   linters = object_name_linter(styles = "dotted.case")
+#' )
+#'
+#' # okay
+#' lint(
+#'   text = "my_var <- 1L",
+#'   linters = object_name_linter(styles = "snake_case")
+#' )
+#'
+#' lint(
+#'   text = "xyz <- 1L",
+#'   linters = object_name_linter(styles = "lowercase")
+#' )
+#'
+#' lint(
+#'   text = "my.var <- 1L; myvar <- 2L",
+#'   linters = object_name_linter(styles = c("dotted.case", "lowercase"))
+#' )
+#'
 #' @evalRd rd_tags("object_name_linter")
 #' @seealso [linters] for a complete list of linters available in lintr.
 #' @export
@@ -172,6 +206,25 @@ regexes_rd <- toString(paste0("\\sQuote{", names(style_regexes), "}"))
 #'   see the detailed note in [object_name_linter()] for more details.
 #'
 #' @param length maximum variable name length allowed.
+#'
+#' @examples
+#' # will produce lints
+#' lint(
+#'   text = "very_very_long_variable_name <- 1L",
+#'   linters = object_length_linter(length = 10L)
+#' )
+#'
+#' # okay
+#' lint(
+#'   text = "very_very_long_variable_name <- 1L",
+#'   linters = object_length_linter(length = 30L)
+#' )
+#'
+#' lint(
+#'   text = "var <- 1L",
+#'   linters = object_length_linter(length = 10L)
+#' )
+#'
 #' @evalRd rd_tags("object_length_linter")
 #' @seealso [linters] for a complete list of linters available in lintr.
 #' @export

R/object_usage_linter.R

@@ -9,6 +9,23 @@
 #'   will be skipped. This argument will be passed to `skipWith` argument of
 #'   `codetools::checkUsage()`.
 #'
+#' @examples
+#' # will produce lints
+#' lint(
+#'   text = "foo <- function() { x <- 1 }",
+#'   linters = object_usage_linter()
+#' )
+#'
+#' # okay
+#' lint(
+#'   text = "foo <- function(x) { x <- 1 }",
+#'   linters = object_usage_linter()
+#' )
+#'
+#' lint(
+#'   text = "foo <- function() { x <- 1; return(x) }",
+#'   linters = object_usage_linter()
+#' )
 #' @evalRd rd_linters("package_development")
 #' @seealso [linters] for a complete list of linters available in lintr.
 #' @export

R/outer_negation_linter.R

@@ -4,6 +4,29 @@
 #'   `all(!x)` and `!any(x)`. Negating after aggregation only requires inverting
 #'   one logical value, and is typically more readable.
 #'
+#' @examples
+#' # will produce lints
+#' lint(
+#'   text = "all(!x)",
+#'   linters = outer_negation_linter()
+#' )
+#'
+#' lint(
+#'   text = "any(!x)",
+#'   linters = outer_negation_linter()
+#' )
+#'
+#' # okay
+#' lint(
+#'   text = "!any(x)",
+#'   linters = outer_negation_linter()
+#' )
+#'
+#' lint(
+#'   text = "!all(x)",
+#'   linters = outer_negation_linter()
+#' )
+#'
 #' @evalRd rd_tags("outer_negation_linter")
 #' @seealso [linters] for a complete list of linters available in lintr.
 #' @export

R/package_hooks_linter.R

@@ -11,6 +11,39 @@
 #' 4. `.onLoad()` and `.onAttach()` should take two arguments, with names matching `^lib` and `^pkg`;
 #'    `.Last.lib()` and `.onDetach()` should take one argument with name matching `^lib`.
 #'
+#' @examples
+#' # will produce lints
+#' lint(
+#'   text = ".onLoad <- function(lib, ...) { }",
+#'   linters = package_hooks_linter()
+#' )
+#'
+#' lint(
+#'   text = ".onAttach <- function(lib, pkg) { require(foo) }",
+#'   linters = package_hooks_linter()
+#' )
+#'
+#' lint(
+#'   text = ".onDetach <- function(pkg) { }",
+#'   linters = package_hooks_linter()
+#' )
+#'
+#' # okay
+#' lint(
+#'   text = ".onLoad <- function(lib, pkg) { }",
+#'   linters = package_hooks_linter()
+#' )
+#'
+#' lint(
+#'   text = ".onAttach <- function(lib, pkg) { loadNamespace('foo') }",
+#'   linters = package_hooks_linter()
+#' )
+#'
+#' lint(
+#'   text = ".onDetach <- function(lib) { }",
+#'   linters = package_hooks_linter()
+#' )
+#'
 #' @evalRd rd_tags("package_hooks_linter")
 #' @seealso [linters] for a complete list of linters available in lintr.
 #' @export

R/paren_body_linter.R

@@ -3,6 +3,20 @@
 #' Check that there is a space between right parenthesis and a body expression.
 #'
 #' @evalRd rd_tags("paren_body_linter")
+#'
+#' @examples
+#' # will produce lints
+#' lint(
+#'   text = "function(x)x + 1",
+#'   linters = paren_body_linter()
+#' )
+#'
+#' # okay
+#' lint(
+#'   text = "function(x) x + 1",
+#'   linters = paren_body_linter()
+#' )
+#'
 #' @seealso
 #'   [linters] for a complete list of linters available in lintr. \cr
 #'   <https://style.tidyverse.org/syntax.html#parentheses>

R/paste_linter.R

@@ -21,6 +21,60 @@
 #'   `paste()` with `sep = ""` is not linted.
 #' @param allow_to_string Logical, default `FALSE`. If `TRUE`, usage of
 #'   `paste()` and `paste0()` with `collapse = ", "` is not linted.
+#'
+#' @examples
+#' # will produce lints
+#' lint(
+#'   text = 'paste("a", "b", sep = "")',
+#'   linters = paste_linter()
+#' )
+#'
+#' lint(
+#'   text = 'paste(c("a", "b"), collapse = ", ")',
+#'   linters = paste_linter()
+#' )
+#'
+#' lint(
+#'   text = 'paste0(c("a", "b"), sep = " ")',
+#'   linters = paste_linter()
+#' )
+#'
+#' lint(
+#'   text = 'paste0(rep("*", 10L), collapse = "")',
+#'   linters = paste_linter()
+#' )
+#'
+#' # okay
+#' lint(
+#'   text = 'paste0("a", "b")',
+#'   linters = paste_linter()
+#' )
+#'
+#' lint(
+#'   text = 'paste("a", "b", sep = "")',
+#'   linters = paste_linter(allow_empty_sep = TRUE)
+#' )
+#'
+#' lint(
+#'   text = 'toString(c("a", "b"))',
+#'   linters = paste_linter()
+#' )
+#'
+#' lint(
+#'   text = 'paste(c("a", "b"), collapse = ", ")',
+#'   linters = paste_linter(allow_to_string = TRUE)
+#' )
+#'
+#' lint(
+#'   text = 'paste(c("a", "b"))',
+#'   linters = paste_linter()
+#' )
+#'
+#' lint(
+#'   text = 'strrep("*", 10L)',
+#'   linters = paste_linter()
+#' )
+#'
 #' @seealso [linters] for a complete list of linters available in lintr.
 #' @export
 paste_linter <- function(allow_empty_sep = FALSE, allow_to_string = FALSE) {

R/pipe_call_linter.R

@@ -1,7 +1,20 @@
 #' Pipe call linter
 #'
-#' Force explicit calls in magrittr pipes, e.g.,
-#' `1:3 %>% sum()` instead of `1:3 %>% sum`.
+#' Force explicit calls in magrittr pipes, e.g., `1:3 %>% sum()` instead of `1:3 %>% sum`.
+#' Note that native pipe always requires a function call, i.e. `1:3 |> sum` will produce an error.
+#'
+#' @examples
+#' # will produce lints
+#' lint(
+#'   text = "1:3 %>% mean %>% as.character",
+#'   linters = pipe_call_linter()
+#' )
+#'
+#' # okay
+#' lint(
+#'   text = "1:3 %>% mean() %>% as.character()",
+#'   linters = pipe_call_linter()
+#' )
 #'
 #' @evalRd rd_tags("pipe_call_linter")
 #' @seealso [linters] for a complete list of linters available in lintr.