From 2e2d9c2f067a0d841e592812ddd50d9cf697a319 Mon Sep 17 00:00:00 2001
From: Hadley Wickham <h.wickham@gmail.com>
Date: Wed, 4 Sep 2024 11:47:04 +0100
Subject: [PATCH] Improve file encryption/decryption docs

Fixes #510
---
 R/secret.R     | 6 +++++-
 man/secrets.Rd | 6 +++++-
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/R/secret.R b/R/secret.R
index 7f1be10c..e0f9cf95 100644
--- a/R/secret.R
+++ b/R/secret.R
@@ -44,6 +44,8 @@
 #' @name secrets
 #' @returns
 #' * `secret_decrypt()` and `secret_encrypt()` return strings.
+#' * `secret_decrypt_file()` returns a path to a temporary file;
+#'   `secret_encrypt_file()` encrypts the file in place.
 #' * `secret_write_rds()` returns `x` invisibly; `secret_read_rds()`
 #'   returns the saved object.
 #' * `secret_make_key()` returns a string with class `AsIs`.
@@ -112,7 +114,9 @@ secret_write_rds <- function(x, path, key) {
 }
 #' @export
 #' @rdname secrets
-#' @param path Path to `.rds` file
+#' @param path Path to file to encrypted file to read or write. For
+#'  `secret_write_rds()` and `secret_read_rds()` this should be an `.rds`
+#'  file.
 secret_read_rds <- function(path, key) {
   enc <- readBin(path, "raw", file.size(path))
   dec_cmp <- secret_decrypt_raw(enc, key)
diff --git a/man/secrets.Rd b/man/secrets.Rd
index fd648995..08131124 100644
--- a/man/secrets.Rd
+++ b/man/secrets.Rd
@@ -38,7 +38,9 @@ the raw vector in directly.}
 
 \item{encrypted}{String to decrypt}
 
-\item{path}{Path to \code{.rds} file}
+\item{path}{Path to file to encrypted file to read or write. For
+\code{secret_write_rds()} and \code{secret_read_rds()} this should be an \code{.rds}
+file.}
 
 \item{envir}{The decrypted file will be automatically deleted when
 this environment exits. You should only need to set this argument if you
@@ -47,6 +49,8 @@ want to pass the unencrypted file to another function.}
 \value{
 \itemize{
 \item \code{secret_decrypt()} and \code{secret_encrypt()} return strings.
+\item \code{secret_decrypt_file()} returns a path to a temporary file;
+\code{secret_encrypt_file()} encrypts the file in place.
 \item \code{secret_write_rds()} returns \code{x} invisibly; \code{secret_read_rds()}
 returns the saved object.
 \item \code{secret_make_key()} returns a string with class \code{AsIs}.