Add more docs on function usage and forbid passing vector as pattern …

…argument.

R/get_files.R

@@ -10,18 +10,39 @@
 #'   to `0`, it will pull files only from `root`, if `1L`, will take data from
 #'   `root` directory and directories visible in `root` directory. If left with
 #'   no argument, will pull files from all directories.
-#' @param file_path A specific path to file(s) in repositories. If defined, the
-#'   function pulls content of this specific `file_path`. May be a character
-#'   vector if multiple files are to be pulled. Can be defined only if `pattern`
-#'   stays `NULL`. It is more efficient to use `file_path` if we know exact file
-#'   from the repository we want to get, e.g. `DESCRIPTION` from `root`
-#'   directory or `R/app.R`.
+#' @param file_path A specific path to file(s) in repositories. May be a
+#'   character vector if multiple files are to be pulled. If defined, the
+#'   function pulls content of this specific `file_path`. Can be defined only if
+#'   `pattern` stays `NULL`.
 #' @param cache A logical, if set to `TRUE` `GitStats` will retrieve the last
 #'   result from its storage.
 #' @param verbose A logical, `TRUE` by default. If `FALSE` messages and printing
 #'   output is switched off.
 #' @param progress A logical, by default set to `verbose` value. If `FALSE` no
 #'   `cli` progress bar will be displayed.
+#' @details `get_files()` may be used in two ways: either with `pattern` (with
+#'   optional `depth`) or `file_path` argument defined.
+#'
+#'   In the first scenario `GitStats` will pull first a files structure
+#'   responding to the passed `pattern` and `depth` arguments and afterwards
+#'   files content for all of these files. In the second scenario `GitStats`
+#'   will pull only the content of files for the given `file_path` of the
+#'   repository.
+#'
+#'   If user wants to pull a particular file or files, a `file_path` approach
+#'   seems to more reasonable, a it is a faster way (it omits pulling the whole
+#'   file structure from the repo).
+#'
+#'   On the other hand, if user wants to pull specific type of files (e.g. `.md`
+#'   or `.Rmd` files), without knowing their path, it is recommended to use a
+#'   `pattern` approach, which will trigger `GitStats` to find all the files in
+#'   the repository on the given level of directories (`pattern` argument) and
+#'   afterwards pull their content.
+#'
+#'   The latter approach is slower than the former but may be more useful
+#'   depending on users' goals. Both approaches return data in the same format:
+#'   `tibble` with data on `files`, namely their `path` and their `content`.
+#'
 #' @examples
 #' \dontrun{
 #'  git_stats <- create_gitstats() |>
@@ -42,7 +63,7 @@
 #'
 #'  app_files <- get_files(
 #'    gitstats = git_stats,
-#'    file_path = "R/app.R"
+#'    file_path = c("R/app.R", "R/ui.R", "R/server.R")
 #'  )
 #'
 #' }
@@ -61,6 +82,12 @@ get_files <- function(gitstats,
       call = NULL
     )
   }
+  if (!is.null(pattern) && length(pattern) > 1) {
+    cli::cli_abort(
+      "Please define regex in one string.",
+      call = NULL
+    )
+  }
   gitstats$get_files(
     pattern = pattern,
     depth = depth,

tests/testthat/_snaps/05-get_files.md

@@ -2,3 +2,7 @@
 
     Please choose either `pattern` or `file_path`.
 
+# error shows when pattern is defined as vector
+
+    Please define regex in one string.
+

tests/testthat/test-05-get_files.R

@@ -94,3 +94,12 @@ test_that("error shows when file_path and pattern are defined at the same time",
               progress = FALSE)
   )
 })
+
+test_that("error shows when pattern is defined as vector", {
+  expect_snapshot_error(
+    get_files(test_gitstats,
+              pattern = c("\\.md", "meta_data.yaml"),
+              verbose = FALSE,
+              progress = FALSE)
+  )
+})