Add example config files to the docs

NEWS.md

@@ -27,7 +27,7 @@
 
 * `infix_spaces_linter()` distinguishes `<-`, `:=`, `<<-` and `->`, `->>`, i.e. `infix_spaces_linter(exclude_operators = "->")` will no longer exclude `->>` (#2115, @MichaelChirico). This change is breaking for users relying on manually-supplied `exclude_operators` containing `"<-"` to also exclude `:=` and `<<-`. The fix is to manually supply `":="` and `"<<-"` as well. We don't expect this change to affect many users, the fix is simple, and the new behavior is much more transparent, so we are including this breakage in a minor release.
 * Removed `find_line()` and `find_column()` entries from `get_source_expressions()` expression-level objects. These have been marked deprecated since version 3.0.0. No users were found on GitHub.
-* There is experimental support for writing config in plain R scripts (as opposed to DCF files; #1210, @MichaelChirico). The script is run in a new environment and variables matching settings (`?default_settings`) are copied over. In particular, this removes the need to write R code in a DCF-friendly way, and allows normal R syntax highlighting in the saved file. We may eventually deprecate the DCF approach in favor of this one; user feedback is welcome on strong preferences for either approach, or for a different approach like YAML. Generally you should be able to convert your existing `.lintr` file to an equivalent R config by replacing the `:` key-value separators with assignments (`<-`). By default, such a config is searched for in a file named '.lintr.R'. This is a mildly breaking change if you happened to be keeping a file '.lintr.R' around since that file is given precedence over '.lintr'.
+* There is experimental support for writing config in plain R scripts (as opposed to DCF files; #1210, @MichaelChirico). The script is run in a new environment and variables matching settings (`?default_settings`) are copied over. In particular, this removes the need to write R code in a DCF-friendly way, and allows normal R syntax highlighting in the saved file. We may eventually deprecate the DCF approach in favor of this one; user feedback is welcome on strong preferences for either approach, or for a different approach like YAML. Generally you should be able to convert your existing `.lintr` file to an equivalent R config by replacing the `:` key-value separators with assignments (`<-`). By default, such a config is searched for in a file named `.lintr.R`. This is a mildly breaking change if you happened to be keeping a file `.lintr.R` around since that file is given precedence over `.lintr`.
   + We also validate config files up-front make it clearer when invalid configs are present (#2195, @MichaelChirico). There is a warning for "invalid" settings, i.e., settings not part of `?default_settings`. We think this is more likely to affect users declaring settings in R, since any variable defined in the config that's not a setting must be removed to make it clearer which variables are settings vs. ancillary.
 
 ## Bug fixes

R/settings.R

@@ -10,6 +10,26 @@
 #' The default linter_file name is `.lintr` but it can be changed with option `lintr.linter_file`
 #'   or the environment variable `R_LINTR_LINTER_FILE`
 #' This file is a DCF file, see [base::read.dcf()] for details.
+#' Here is an example of a `.lintr` file:
+#'
+#'  ```dcf
+#'  linters: linters_with_defaults(
+#'      any_duplicated_linter(),
+#'      any_is_na_linter(),
+#'      backport_linter("oldrel-4", except = c("R_user_dir", "str2lang")),
+#'      line_length_linter(120),
+#'      missing_argument_linter(),
+#'      unnecessary_concatenation_linter(allow_single_expression = FALSE),
+#'      yoda_test_linter()
+#'    )
+#'  exclusions: list(
+#'      "inst/doc/creating_linters.R" = 1,
+#'      "inst/example/bad.R",
+#'      "tests/testthat/default_linter_testcode.R",
+#'      "tests/testthat/dummy_packages"
+#'    )
+#' ```
+#'
 #' Experimentally, we also support keeping the config in a plain R file. By default we look for
 #'   a file named `.lintr.R` (in the same directories where we search for `.lintr`).
 #' We are still deciding the future of config support in lintr, so user feedback is welcome.
@@ -20,6 +40,25 @@
 #"   otherwise "abusing" the ability to evaluate generic R code. Other recursive key-value stores
 #'   like YAML could work, but require new dependencies and are harder to parse
 #'   both programmatically and visually.
+#' Here is an example of a `.lintr.R` file:
+#'
+#'  ```r
+#'  linters <- linters_with_defaults(
+#'      any_duplicated_linter(),
+#'      any_is_na_linter(),
+#'      backport_linter("oldrel-4", except = c("R_user_dir", "str2lang")),
+#'      line_length_linter(120),
+#'      missing_argument_linter(),
+#'      unnecessary_concatenation_linter(allow_single_expression = FALSE),
+#'      yoda_test_linter()
+#'    )
+#'  exclusions <- list(
+#'      "inst/doc/creating_linters.R" = 1,
+#'      "inst/example/bad.R",
+#'      "tests/testthat/default_linter_testcode.R",
+#'      "tests/testthat/dummy_packages"
+#'    )
+#' ```
 #' @param filename Source file to be linted.
 read_settings <- function(filename) {
   reset_settings()