From 2a1ab6371070679fb1b882606a474a0e67c7c0c5 Mon Sep 17 00:00:00 2001
From: Greg Freedman Ellis <greg@crunch.io>
Date: Wed, 12 May 2021 10:51:13 -0500
Subject: [PATCH] better docs

---
 R/api.R                    | 7 ++++---
 R/automation.R             | 5 +++--
 man/crunchAPI.Rd           | 5 +++--
 man/handleAPIresponse.Rd   | 5 +++--
 man/runCrunchAutomation.Rd | 5 +++--
 5 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/R/api.R b/R/api.R
index 3fef22af0..5f5b94d60 100644
--- a/R/api.R
+++ b/R/api.R
@@ -7,7 +7,7 @@
 #' @param status.handlers named list of specific HTTP statuses and a response
 #' function to call in the case where that status is returned. Passed to the
 #' [handleAPIresponse()] function.
-#' progress.handler an optional function that resolves errors raised
+#' @param progress.handler an optional function that resolves errors raised
 #' during an async request. Passed to the [`pollProgress()`] function.
 #' @keywords internal
 crunchAPI <- function(http.verb, url, config = list(), status.handlers = list(), progress.handler = NULL, ...) {
@@ -57,8 +57,9 @@ crDELETE <- function(...) crunchAPI("DELETE", ...)
 #' Do the right thing with the HTTP response
 #' @param response an httr response object
 #' @param special.statuses an optional named list of functions by status code.
-#' @param progress.handler an optional function that resolves errors raised
-#' during an async request
+#' @param progress.handler an optional function to handle errors reported by
+#' a progress result. Default NULL prints the string `message`; other
+#' functions required to handle non-string messages in progress responses.
 #' @return The full HTTP response object, just the content, or any other
 #' status-specific action
 #' @importFrom httr content http_status
diff --git a/R/automation.R b/R/automation.R
index cfe0c1941..319f52d31 100644
--- a/R/automation.R
+++ b/R/automation.R
@@ -102,8 +102,9 @@ setMethod("scriptSavepoint", "Script", function(x) {
 #' @param is_file The default guesses whether a file or string was
 #' used in the `script` argument, but you can override the heuristics
 #' by specifying `TRUE` for a file, and `FALSE` for a string.
-#' @param encoding The encoding the script file is saved as on your
-#' machine. Defaults to UTF-8.
+#' @param encoding Optional encoding to convert **from**, defaults to UTF-8.
+#' The API accepts only UTF-8, so all text will be converted to UTF-8 before
+#' being sent to the server.
 #' @param ... Additional options, such as `dry_run = TRUE` passed on
 #' to the API
 #'
diff --git a/man/crunchAPI.Rd b/man/crunchAPI.Rd
index 3b4d763ce..f375a4d14 100644
--- a/man/crunchAPI.Rd
+++ b/man/crunchAPI.Rd
@@ -22,8 +22,9 @@ crunchAPI(
 
 \item{status.handlers}{named list of specific HTTP statuses and a response
 function to call in the case where that status is returned. Passed to the
-\code{\link[=handleAPIresponse]{handleAPIresponse()}} function.
-progress.handler an optional function that resolves errors raised
+\code{\link[=handleAPIresponse]{handleAPIresponse()}} function.}
+
+\item{progress.handler}{an optional function that resolves errors raised
 during an async request. Passed to the \code{\link[=pollProgress]{pollProgress()}} function.}
 
 \item{...}{additional arguments passed to \code{GET}, \code{PUT},
diff --git a/man/handleAPIresponse.Rd b/man/handleAPIresponse.Rd
index ee2a77acc..96ec8d5c7 100644
--- a/man/handleAPIresponse.Rd
+++ b/man/handleAPIresponse.Rd
@@ -11,8 +11,9 @@ handleAPIresponse(response, special.statuses = list(), progress.handler = NULL)
 
 \item{special.statuses}{an optional named list of functions by status code.}
 
-\item{progress.handler}{an optional function that resolves errors raised
-during an async request}
+\item{progress.handler}{an optional function to handle errors reported by
+a progress result. Default NULL prints the string \code{message}; other
+functions required to handle non-string messages in progress responses.}
 }
 \value{
 The full HTTP response object, just the content, or any other
diff --git a/man/runCrunchAutomation.Rd b/man/runCrunchAutomation.Rd
index a46459a85..dbf119775 100644
--- a/man/runCrunchAutomation.Rd
+++ b/man/runCrunchAutomation.Rd
@@ -25,8 +25,9 @@ or a string the syntax loaded in R.}
 used in the \code{script} argument, but you can override the heuristics
 by specifying \code{TRUE} for a file, and \code{FALSE} for a string.}
 
-\item{encoding}{The encoding the script file is saved as on your
-machine. Defaults to UTF-8.}
+\item{encoding}{Optional encoding to convert \strong{from}, defaults to UTF-8.
+The API accepts only UTF-8, so all text will be converted to UTF-8 before
+being sent to the server.}
 
 \item{...}{Additional options, such as \code{dry_run = TRUE} passed on
 to the API}