From c1c874fe7a1e7dbde86df8affac095d1cfa8014a Mon Sep 17 00:00:00 2001
From: Ashby Thorpe <ashbythorpe@gmail.com>
Date: Wed, 25 Oct 2023 16:07:24 +0100
Subject: [PATCH] Document and clean up functions

---
 R/predl_chrome_for_testing.R       | 59 +++++++++++++++++++-----------
 inst/etc/checks.R                  |  1 +
 inst/yaml/chromedriver_testing.yml |  2 -
 man/predl_chrome_for_testing.Rd    | 35 ++++++++----------
 man/unziptar_chromedriver.Rd       | 18 +++++++--
 5 files changed, 69 insertions(+), 46 deletions(-)

diff --git a/R/predl_chrome_for_testing.R b/R/predl_chrome_for_testing.R
index c82dbb1..40c235b 100644
--- a/R/predl_chrome_for_testing.R
+++ b/R/predl_chrome_for_testing.R
@@ -1,33 +1,38 @@
-#' Pre-download function for Chrome-for-testing site
+#' Pre-download function for Chrome for Testing site
 #'
-#' @param url URL of the JSON to use for files
+#' Prepare to download Chromedriver from the Chrome for Testing site.
+#'
+#' @param url URL containing the JSON used to locate files.
 #' @param platform One of `c("linux64", "mac-arm64", "mac-x64",
-#'                           "win32", "win64")
-#' @param history Integer number of recent entries
-#' @param appname Name of the app, typically `"chromedriver"`
-#' @param platformregex A filter for platforms. Defaults to the platform names.
+#'                           "win32", "win64")`.
+#'
+#' @return
+#' A named list of dataframes. The name indicates the platform. The
+#' dataframe should contain the version, url, and file to be processed.
+#' Used as input for [binman::download_files()] or equivalent.
+#'
+#' @examples
+#' \dontrun{
+#' # predl_chrome_for_testing() is used by chrome()
+#' chrome <- chrome()
+#' chrome$stop()
+#' }
 #'
-#' @return A named list of dataframes.  The name indicates the platform.  The dataframe should contain the version, url, and file to
-#' be processed.  Used as input for `binman::download_files()` or an equivalent.
 #' @importFrom binman assign_directory
+#'
 #' @export
-predl_chrome_for_testing <- function(url, platform, history,
-                                     appname,
-                                     platformregex = platform) {
+predl_chrome_for_testing <- function(url, platform) {
   assert_that(is_URL_file(url))
   assert_that(is_character(platform))
-  assert_that(is_integer(history))
-  assert_that(is_string(appname))
-  assert_that(is_character(platformregex))
   ver_data <- jsonlite::fromJSON(url)[[2]]
   ver_data <- Filter(
-    function(x) !is.null(x$downloads[[appname]]),
+    function(x) !is.null(x$downloads[["chromedriver"]]),
     ver_data
   )
   ver_data <- ver_data[order(as.numeric(names(ver_data)))]
   unwrap <- function(entry) {
     version <- entry$version
-    downloads <- entry$downloads[[appname]]
+    downloads <- entry$downloads[["chromedriver"]]
     if (!is.null(downloads)) {
       platform <- downloads$platform
       url <- downloads$url
@@ -38,7 +43,7 @@ predl_chrome_for_testing <- function(url, platform, history,
   extracted <- do.call(rbind, lapply(ver_data, unwrap))
   app_links <- tapply_identity(extracted, extracted$platform)
   app_links <- app_links[platform]
-  assign_directory(app_links, appname)
+  assign_directory(app_links, "chromedriver")
 }
 
 # The same as tapply(x, y, identity), but works on older versions of R.
@@ -55,14 +60,24 @@ tapply_identity <- function(x, y) {
 #' Unzip or untar a downloaded chromedriver file, then extract it from
 #' its folder.
 #'
-#' @param ... Passed into [binman::unziptar_dlfiles].
+#' @param dlfiles Passed into [binman::unziptar_dlfiles]: A data frame of
+#'   files.
+#' @param chmod If `TRUE`, the files are made executable.
+#'
+#' @returns The same as [binman::unziptar_dlfiles()]: a list of character
+#'   vectors representing the processed files.
 #'
-#' @return The same as [binman::unziptar_dlfiles].
+#' @examples
+#' \dontrun{
+#' # unziptar_chromedriver() is used by chrome()
+#' chrome <- chrome()
+#' chrome$stop()
+#' }
 #'
 #' @export
-unziptar_chromedriver <- function(...) {
-  chmod <- list(...)$chmod
-  x <- binman::unziptar_dlfiles(...)
+unziptar_chromedriver <- function(dlfiles, chmod = TRUE) {
+  x <- binman::unziptar_dlfiles(dlfiles, chmod = chmod)
+
   for (f in x$processed) {
     dir <- tools::file_path_sans_ext(f)
     file.copy(list.files(dir, full.names = TRUE), dirname(dir), copy.mode = TRUE)
diff --git a/inst/etc/checks.R b/inst/etc/checks.R
index 519e77e..f0e8928 100644
--- a/inst/etc/checks.R
+++ b/inst/etc/checks.R
@@ -18,6 +18,7 @@ tries$chrome <- tryCatch(
 
 tries$chrome_old <- tryCatch(
   {
+    # Version of chrome that is not on the Chrome for Testing site
     print("chrome (old)")
     tmp <- chrome(verbose = TRUE, version = "114.0.5735.90")
     print(tmp$log())
diff --git a/inst/yaml/chromedriver_testing.yml b/inst/yaml/chromedriver_testing.yml
index e212729..55b2b4d 100644
--- a/inst/yaml/chromedriver_testing.yml
+++ b/inst/yaml/chromedriver_testing.yml
@@ -8,8 +8,6 @@ predlfunction:
     - linux64
     - win32
     - win64
-    history: 3
-    appname: "chromedriver"
 dlfunction:
   "binman::download_files": []
 postdlfunction:
diff --git a/man/predl_chrome_for_testing.Rd b/man/predl_chrome_for_testing.Rd
index e8b89e0..a57266b 100644
--- a/man/predl_chrome_for_testing.Rd
+++ b/man/predl_chrome_for_testing.Rd
@@ -2,32 +2,29 @@
 % Please edit documentation in R/predl_chrome_for_testing.R
 \name{predl_chrome_for_testing}
 \alias{predl_chrome_for_testing}
-\title{Pre-download function for Chrome-for-testing site}
+\title{Pre-download function for Chrome for Testing site}
 \usage{
-predl_chrome_for_testing(
-  url,
-  platform,
-  history,
-  appname,
-  platformregex = platform
-)
+predl_chrome_for_testing(url, platform)
 }
 \arguments{
-\item{url}{URL of the JSON to use for files}
+\item{url}{URL containing the JSON used to locate files.}
 
 \item{platform}{One of `c("linux64", "mac-arm64", "mac-x64",
-"win32", "win64")}
-
-\item{history}{Integer number of recent entries}
-
-\item{appname}{Name of the app, typically `"chromedriver"`}
-
-\item{platformregex}{A filter for platforms. Defaults to the platform names.}
+"win32", "win64")`.}
 }
 \value{
-A named list of dataframes.  The name indicates the platform.  The dataframe should contain the version, url, and file to
-be processed.  Used as input for `binman::download_files()` or an equivalent.
+A named list of dataframes. The name indicates the platform. The
+dataframe should contain the version, url, and file to be processed.
+Used as input for [binman::download_files()] or equivalent.
 }
 \description{
-Pre-download function for Chrome-for-testing site
+Prepare to download Chromedriver from the Chrome for Testing site.
+}
+\examples{
+\dontrun{
+# predl_chrome_for_testing() is used by chrome()
+chrome <- chrome()
+chrome$stop()
+}
+
 }
diff --git a/man/unziptar_chromedriver.Rd b/man/unziptar_chromedriver.Rd
index 0c8ef5c..dcb7a22 100644
--- a/man/unziptar_chromedriver.Rd
+++ b/man/unziptar_chromedriver.Rd
@@ -4,15 +4,27 @@
 \alias{unziptar_chromedriver}
 \title{Unzip/untar the chromedriver file}
 \usage{
-unziptar_chromedriver(...)
+unziptar_chromedriver(dlfiles, chmod = TRUE)
 }
 \arguments{
-\item{...}{Passed into [binman::unziptar_dlfiles].}
+\item{dlfiles}{Passed into [binman::unziptar_dlfiles]: A data frame of
+files.}
+
+\item{chmod}{If `TRUE`, the files are made executable.}
 }
 \value{
-The same as [binman::unziptar_dlfiles].
+The same as [binman::unziptar_dlfiles()]: a list of character
+  vectors representing the processed files.
 }
 \description{
 Unzip or untar a downloaded chromedriver file, then extract it from
 its folder.
 }
+\examples{
+\dontrun{
+# unziptar_chromedriver() is used by chrome()
+chrome <- chrome()
+chrome$stop()
+}
+
+}